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Preface 


Manual Objectives 


The VAX FORTRAN User's Guide is intended as a support document for large or sophisti¬ 
cated development efforts on which the VAX FORTRAN product is the principal language. 
Most of the information in this manual is specific to VAX FORTRAN and thus is not recom¬ 
mended in those cases in which program portability is particularly important. 

This manual describes performance optimizations, both those built into the compiler and 
those that you can build into your programs. It also describes many of the important 
VAX/VMS system services that you can access from VAX FORTRAN programs, and it dis¬ 
cusses language features that perform differently between FORTRAN-77 and 
FORTRAN-66 and between VAX FORTRAN and PDP-11 FORTRAN. 

A complete description of VAX FORTRAN language elements is contained in Program¬ 
ming in VAX FORTRAN, along with information on how to compile, link, run, and debug 
VAX FORTRAN programs. 



Intended Audience 


This manual is designed for programmers who have a detailed knowledge of FORTRAN 
and a working knowledge of VAX/VMS. In the sections of this book requiring an extensive 
understanding of the operating system (condition handling, for instance), you are directed 
to the appropriate manual(s) for supplementary information. 


Structure of this Document 


The following list outlines the organization and chapter content of this manual. 

• Chapter 1 describes how you can optimize the efficiency of your FORTRAN programs. 
It also describes many of the optimizations performed by the compiler itself. 

• Chapter 2 describes the relationship between VAX FORTRAN and the VAX system; 
it includes information on program section usage, data types, functions, DO loop iter¬ 
ation, and floating-point data representation. 

• Chapter 3 discusses the conventions followed in calling procedures, especially the 
argument-passing conventions. 



ix 




• Chapter 4 provides information on the use of RMS (Record Management Services). 

• Chapter 5 describes how local and remote processes can share and exchange data. 

• Chapter 6 describes the condition-handling facility. This chapter is intended for users 
with in-depth knowledge of VAX/VMS. 

• Appendix A discusses compatibility between VAX FORTRAN (FORTRAN-77 lan¬ 
guage) and implementations of FORTRAN which are based on the FORTRAN-66 
standard. 

• Appendix B discusses compatibility between VAX FORTRAN and PDP-11 
FORTRAN. 

• Appendix C summarizes the modules located in the FORTRAN system library 
FORSYSDEF. 

• Appendix D contains sample FORTRAN programs that access system services. 

Associated Documents 

The following documents contain information that is relevant to programming issues 
addressed in this manual: 

• Introduction to VAX/VMS 

• Programming in VAX FORTRAN 

• Guide to Using DCL and Command Procedures on VAX/VMS 

• VAX/VMS Run-Time Library Reference Manual 

• Introduction to VAX Record Management Services 

• VAX Record Management Services Reference Manual 

• VAX Record Management Services Tuning Guide 

• VAX/VMS Linker Reference Manual 

• VAX/VMS System Services Reference Manual 

• VAX-11 Architecture Reference Manual 

For a complete list of VAX software documents, see the VAX/VMS Master Index. 

Conventions Used in this Document 

The following conventions are observed in this manual. 

• Uppercase words and letters, used in examples, indicate that you should type the 
word or letter exactly as shown. 


• Lowercase words and letters, used in syntax examples, indicate that you are to substi¬ 
tute a word or value of your choice. 

• Brackets ([ ]) indicate optional elements, except when they enclose a directory 
specifier. 

• Braces ({ }) enclose lists from which one element is to be chosen. 

• Ellipses (...) indicate that the preceding item(s) can be repeated one or more times. 

• “Real” (lowercase) is used to refer to the REAL*4 (REAL), REAL*8, and REAL* 16 
data types as a group; likewise, “complex” (lowercase) is used to refer to the COM- 
PLEX*8 (COMPLEX) and COMPLEX* 16 data types as a group; “logical” (lowercase) 
is used to refer to the LOGICAL*2 and LOGICAL*4 data types as a group; and “inte¬ 
ger” (lowercase) is used to refer to the INTEGER*2 and INTEGER*4 data types as a 
group. 

In addition, the following symbols denote significant special nonprinting characters: 

Space character: A 

Carriage return: <RET> 
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Chapter 1 

Performance Optimization 


The word optimization , as used in this chapter, refers to the process of improving the effi¬ 
ciency of programs. The objective of optimization is to produce source and object programs 
that achieve the greatest amount of processing with the least amount of time and memory. 

Optimum efficiency results when programs are carefully designed and written, and when 
compilation techniques take advantage of the machine architecture. The VAX FORTRAN 
compiler produces efficient code by utilizing the benefits of the VAX native-mode architec¬ 
ture and hardware. The primary goal of optimization performed by the VAX FORTRAN 
compiler is faster execution. A secondary goal is to reduce the size of the object program. 

The language elements you use in the source program directly affect the compiler’s ability 
to optimize the object program. Therefore, you should be aware of the ways in which you 
can assist compiler optimization. In addition, this awareness will often make it easier for 
you to track down the source of a problem when your program exhibits unexpected 
behavior. 

This chapter describes optimization techniques used by the compiler and coding practices 
that promote optimization, both in relation to the compiler and in relation to the VAX sys¬ 
tem in general. 

The chapter is divided into six major sections: 

• Section 1.1, General Optimization Issues , covers a variety of issues, including how 
optimization affects machine code and diagnostics, how the selection of source-pro- 
gram algorithms affect efficiency, and how the compiler functions. 

• Section 1.2, Effects of Compiler Optimizations on Debugging , discusses why debug¬ 
ging is best done on unoptimized programs. 

• Section 1.3, Global Analysis of Variables and Arrays , describes how the compiler per¬ 
forms a global analysis of the variables and arrays used in a program unit. It explains 
how the variables are selected and the constructs and declarations in the source code 
that influence that selection. 

• Section 1.4, Speed Optimizations , describes optimizations that improve the running 
time of programs. 

• Section 1.5, Space Optimizations , discusses optimizations that decrease the memory 
used by programs. 


1-1 




• Section 1.6, Compiler Optimization Example , provides an example that illustrates the 
optimizations described earlier in the chapter and demonstrates the performance 
enhancements. 

In this chapter, much of the material in the later sections assumes that you are familiar 
with material in earlier sections. Understanding the material in Section 1.3 is particu¬ 
larly important. 


1.1 General Optimization Issues 

This section presents background information that you need to know in order to use your 
time and efforts wisely when trying to improve the run-time performance of your pro¬ 
grams. It contains information on the following areas: 

• It explains how sound coding practices can have a far greater influence on efficiency 
than compiler optimizations. 

• It describes the differences and similarities of optimized and unoptimized code. 

• It provides an overview of how the compiler operates and the internal data structures 
that it uses. 

1.1.1 Importance of Algorithms Used in Source Programs 

There are often several ways that a given problem can be attacked using a computer pro¬ 
gram. The method chosen usually has more effect on the performance of the program than 
any amount of compiler optimization. Thus, in an effort to improve the performance of a 
program, it is often useful to look for a faster general method, rather than trying to make 
the individual operations faster. 

To illustrate the importance of the algorithm used to solve a problem, consider the problem 
of searching for a given value in a sorted list. You can use many different methods to search 
for a value, and each method has advantages and disadvantages relative to the others. 
Each method is characterized by a certain number of fundamental operations that it must 
perform. For instance, the fundamental operations of a simple linear search are tests, for 
example: 
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UAL 


C Assumes A is sorted in ascending order 
C Returns the ualue of INDEX at which A(INDEX) ♦EQ♦ 

C Returns INDEX = 0 if none 
C 

SUBROUTINE SEARCH(A »N»U A L»INDEX) 

INTEGER A(N) »UAL 
INDEX = 0 
DO 30 1 = 1 »N 

IF (UAL-A(I) ) 10 t 20 » 30 

10 INDEX = 0 

RETURN 

20 INDEX = I 

RETURN 

30 CONTINUE 

END 

No matter how well the compiler optimizes the tests, it will take, on average, N tests 
(including the loop ending tests) to find the desired value. Alternatively, consider the fol¬ 
lowing binary search method, which is more complicated but takes only about 2 * (LOG N 
(base 2)) tests: 

SUBROUTINE SEARCH(A >N»UAL,INDEX) 

INTEGER A(N) >UAL > HI BOUND t LOBOUND 
HIBOUND = N 

LOBOUND = 1 

DO 40 WHILE (HIBOUND ♦GE ♦ LOBOUND) 

I = (HIBOUND + LOBOUND) / 2 



IF (A(I)-UAL) 

10» 20 * 30 

10 

LOBOUND = I + 

1 


GO TO 40 


20 

INDEX = I 



RETURN 


30 

HIBOUND = I - 

1 

40 

CONTINUE 



INDEX = 0 



END 

Note that for N = 1000 the sequential search will average about 1000 tests in the loop, and 
the binary search will average about 20 (including the loop termination tests). No matter 
how much optimization is applied to the linear search, it will be much slower than the 
binary search. 

Compiler optimization generally makes only the operations specified by your source pro¬ 
gram run faster; it cannot make algorithm transformations. For this reason, it is impor¬ 
tant that you try to use a faster algorithm before trying to improve the optimization of the 
individual operations. 


1.1.2 Characteristics of Optimized and Unoptimized Programs 

Optimized programs produce results and run-time diagnostic messages identical to those 
produced by equivalent unoptimized programs. However, an optimized program may pro¬ 
duce fewer run-time diagnostics, and the diagnostics may occur at different source pro¬ 
gram statements or in a different order. For example: 
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Unoptimized Code 


Optimized Code 


10 


A = X/Y 
B = X/Y 
DO 10 » 1 = 1 »10 
C ( I ) = C ( I ) * ( X / Y ) 


10 


t = X/Y 
A = t 
B = t 

DO 10 » 1 = 1 *10 
C(I) = C(I)*t 


The value of Y may be 0.0. Thus, the unoptimized program may produce up to 12 divide-by¬ 
zero errors at run time (that is, if you provide code in your program to handle the error), 
and the optimized program never produces more than one. (Note that t is a temporary vari¬ 
able created by the compiler.) 

Eliminating redundant calculations and moving invariant calculations out of loops can 
affect detection of arithmetic errors, and you should keep this in mind when you include 
error-detecting routines in your program. 

1.1.3 Compiler Structure 

Some of the guidelines described in later sections on how best to take advantage of com¬ 
piler optimizations arise because of the structure of the compiler. Because the compiler 
tries to trade off compile time and run time, it has limitations on the number and kinds of 
constructs that it will optimize. This section describes the overall design of the compiler 
and how it achieves its optimizations. This information is intended to explain why the 
restriction hints described in the later sections arise. 

The VAX FORTRAN V4 compiler transforms your source program to VAX object code in a 
series of stages, called phases. Each phase transforms the program in a certain way and 
gathers information in preparation for the next phase. The order of the phases is chosen so 
that the transformations in the earlier phases increase the effectiveness of the later 
phases. Some phases are optional. The phases that are actually executed for any given 
program depend on its complexity, whether source errors were found, whether the 
/NOOPTIMIZE qualifier is used, and what optimizations actually take effect. 

At various points in the compilation process, the program is represented in a series of 
intermediate forms as data structures in VAX memory. In general, these structures are 
considerably larger than either the original source representation or the final object repre¬ 
sentation. The actual operation of each phase consists of modifications to these internal 
data structures. 

1.2 Effects of Compiler Optimizations on Debugging 

The VAX FORTRAN compiler provides the /NOOPTIMIZE qualifier to disable many of its 
optimizations. This qualifier is provided to facilitate debugging of FORTRAN programs 
with VAX DEBUG. If the /NOOPTIMIZE qualifier is not used, many debugging commands 
will not work as expected. In general, the use of /NOOPTIMIZE will affect compile speed 
only marginally. 
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If you wish to debug optimized programs, you may need to reference a compiler listing of 
the machine code generated by the compiler. Therefore, if you do not suppress optimiza¬ 
tion, you should specify the /LIST and /MACHINE_CODE qualifiers on your FORTRAN 
command. 

Some of the ways that machine code optimizations can affect debugging operations are 
described below. 

• Coding order. Some of the compiler optimizations cause code to be generated in an 
order that differs from the order in which it appears in the source. Sometimes code is 
eliminated altogether. This causes unexpected behavior when you are using the 
debugger to step through the code or to display the source lines. 

• Control flow. If there are no intervening labels, the compiler assumes that statements 
are executed in the sequence in which they appear in source code. The compiler also 
eliminates label definitions if they are not needed in the machine code. As a result, 
you cannot reference such labels using the debugger %LABEL commands. 

• Use of condition codes. This optimization technique takes advantage of the way in 
which the VAX processor condition codes are set. For example, consider the following 
source code: 

X = X + 2*5 

IF (X ♦LT♦ 0*0) GO TO 20 

Rather than test the new value of X to determine whether to branch, the optimized 
machine code bases its decision on the condition code settings after 2.5 is added to X. 
Thus, if you attempt to set a debugging breakpoint at the second line and deposit a 
different value into X, you will not achieve the intended result because the condition 
codes no longer reflect the value of X. In other words, the decision to branch is made 
without regard to the deposited value of the variable. 

• Use of registers. Some of the compiler optimizations make use of VAX general purpose 
registers to speed up operations. When the value of a variable is being held in a regis¬ 
ter, its value in memory is generally invalid. Often a spurious value will be displayed 
if the EXAMINE command is issued for a variable under these circumstances. Some¬ 
times the compiler is able to determine that the value of a variable is not needed in 
memory at all. In this case, the variable is not allocated a memory address, and the 
address field for the variable is given as “**” in the memory map part of the compiler 
output listing. Attempting to examine such a variable will result in a warning mes¬ 
sage from the debugger. 

You can avoid these problems, as well as several others, by compiling with the 
/NOOPTIMIZE qualifier. 

The use of some features of the VAX architecture will cause programs to violate the rules 
and prohibitions of the VAX FORTRAN language. In many of these cases, these rules can¬ 
not be checked efficiently at either compile time or run time, and no error messages are 
generated. However, the use of these features will, in some cases, interact with compiler 
optimizations and cause unexpected results. In most cases, you can overcome such 
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problems by declaring the affected variables with the VOLATILE statement (see Section 
1.3.2.2). While tracking the problem down, you may find it convenient to use the 
/NOOPTIMIZE qualifier to disable all optimizations and get the program working quickly. 

1.3 Global Analysis of the Use of Variables and Arrays 

The compiler optimizes an entire program unit at a time. Several of its phases are devoted 
to tracing the values of variables and array elements as they are created and used in differ¬ 
ent parts of the program unit. This process is called global data flow analysis and is an 
important part of many optimizations. One particular usage of the language degrades the 
effectiveness of this process and thus prevents optimizations that would be possible if a 
different source construct were used to perform the same function. This usage is the 
assigned GOTO statement. 

An assigned GOTO degrades optimizations because the compiler assumes that any of the 
labels that have been assigned to the variable anywhere in the program are possible desti¬ 
nations of the GOTO. For example, consider the following program fragment: 

A = 5 ♦ 0 

ASSIGN 10 TO LAB 
GO TO LAB 
ASSIGN 20 TO LAB 
20 A = X + Y 

10 B = A + 4*0 

In this example, the compiler would try to propagate the value of 5.0 for A to the assign¬ 
ment to B. If this were possible, that statement could be simplified to B = 9.0. However, the 
second ASSIGN statement means that the compiler must assume that A can be changed 
before its use. If a computed GOTO or a simple GOTO were used instead, the compiler can 
do the necessary analysis to allow the optimization. 

1.3.1 Criteria for Selecting Variables and Arrays for Global Analysis 

The global data flow analysis done by the compiler primarily consists of tracing the use of 
variables and arrays throughout a program unit. The speed with which this analysis can 
be accomplished depends partly on how many variables and arrays are to be analyzed. For 
this reason, the compiler puts an upper limit on the number of variables and arrays for 
which it performs the global analysis. The compiler uses heuristic methods to select the 
variables and arrays in the program unit that would benefit most from analysis. It then 
limits its analysis to those variables and arrays that are selected. 

In general, the selection methods are biased toward the most heavily used variables and 
arrays. Each appearance of a variable or array in the source program counts as a use, and 
uses inside DO loops count extra. 
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1.3.2 Factors Influencing Global Analysis 

The use of EQUIVALENCE statements, volatile declarations, statement functions, and 
variable format expressions can affect global analysis. These factors are discussed in the 
sections that follow. 

1.3.2.1 Effects of EQUIVALENCE Statements - Because quantities in EQUIVALENCE 
groups share memory locations, when variables and arrays are used in EQUIVALENCE 
statements, the optimizer must ensure that effects of using one variable or array in the 
equivalence group are accounted for with regard to assignments to the other variables and 
arrays. For example: 

EQUIVALENCE < A >B) 

A = 4.0 

B = X + 1 

Z = A + 5.0 

The compiler does not allow the value of 4.0 for A to be propagated to the assignment to Z 
because of the assignment to B. 

For this reason, the variables and arrays used in EQUIVALENCE statements in each sep¬ 
arate PSECT (common block) are grouped together and analyzed as if they were a single 
array during global analysis. As a result, global analysis is usually more effective if unnec¬ 
essary EQUIVALENCE statements are avoided. 

In particular, EQUIVALENCE statements are often used to decrease the memory require¬ 
ments of programs originally written for use on computers with address spaces that are 
smaller than those provided by VAX systems. Because this exercise is usually unnecessary 
on a VAX computer, you can often improve compiler optimization in these programs by 
removing unnecessary EQUIVALENCE statements. In general, for best optimization, you 
should separate the uses of arrays and variables by the role they fill and not use the same 
storage location for two different roles within the program. In addition to performance 
benefits, the removal of the unnecessary EQUIVALENCE statements can make debug¬ 
ging easier. 

1.3.2.2 Effects of Volatile Declarations - The VOLATILE statement is provided by VAX 
FORTRAN as an extension to the standard FORTRAN 77 language. Its purpose is to allow 
your programs to use certain run-time features of the VAX environment that violate the 
rules and prohibitions of the VAX FORTRAN language, but at the same time take full 
advantage of the optimization capabilities of the VAX FORTRAN compiler. When vari¬ 
ables, arrays, or common blocks are declared volatile, they are never selected for global 
analysis. In addition, many of the local optimizations described below are also disabled. If 
these optimizations are not disabled, they may cause the program to exhibit unexpected 
behavior. In general, this unexpected behavior will be intermittent and hard to trace. 
Some of the circumstances in which volatile declarations should be used are described 
below. 
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• When using variables in shared global common 

Using a combination of link-time and run-time options, it is possible for two different 
FORTRAN programs running at the same time to use shared memory to communi¬ 
cate. These programs may be running on a single CPU sharing standard main mem¬ 
ory, or they may be running on different CPUs accessing a block of storage in a 
multiport memory unit. In addition, some special I/O devices can be controlled by 
sharing memory with a FORTRAN program. This shared memory must be declared 
as common blocks and must be page aligned. This usage is referred to as shared global 
common. This method is often the fastest way for two programs to communicate large 
amounts of data on VAX. Shared global commons should always be declared VOLA¬ 
TILE when the contents may change without synchronization with the program unit. 
See Section 5.1.2 for more information about how to use shared global commons. 

• When using variables in a condition handler 

FORTRAN programs can take advantage of the VAX condition handling mecha¬ 
nisms. These mechanisms can be used in various cases in which control is taken away 
from the normal execution order of the program and given to a special routine called a 
condition handler. 

When writing programs that use these exception mechanisms, you should always 
declare as volatile any variables or arrays that are shared between the condition han¬ 
dler and the program. Failure to do this may cause the condition handler to use an 
incorrect value for the shared quantity, or cause the program to ignore handler modi¬ 
fications of the shared quantity. See Chapter 6 for more information about the use of 
the VAX exception handling mechanisms. 

• When remembering the addresses of arguments in a subroutine 

Some subprograms have the capability to retain the addresses of their arguments 
after they have returned, and can reuse those addresses in later calls even though the 
arguments do not explicitly appear in the argument list for those calls. When calling 
such subprograms, you should always declare the arguments whose addresses are 
retained as volatile. This prevents the compiler from holding them in registers across 
later calls. 

Most often, this situation applies to those systems of routines for which you must 
make an initialization call with an array to be used for “working storage” while the 
system is being used. The arrays used for working storage should be declared as 
volatile. 

1.3.2.3 Effects of Inline Expansion of Statement Functions - The compiler will attempt to 
expand statement functions directly inline, rather than call them as functions. This has 
several performance benefits: 

• It allows the expression inside the statement function to participate in the global 
analysis performed on the rest of the program. 

• It saves the overhead of a subprogram call and return. 
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• It eliminates both the need to store the actual arguments in memory before the call 
and the need to retrieve them from memory after the call. 

For example: 

Unoptimized Code Optimized Code 

SUM( A > B ) = A + B SUM(A »B ) = A + B 


Y = 3*14 Y = 3 . 1 a 

X = SUM(Y »3♦0) X = 6.14 

You can determine from an compiler output listing whether a statement function is always 
expanded inline. For program units that contain statement functions, a summary of the 
statement functions is printed at the bottom of the listing. The address and data type of 
each statement function is listed. If the address is specified as then it was expanded 
inline each time it was referenced. 

Not all statement functions can be expanded inline, however. Several criteria are used to 
determine whether the statement function can be expanded. These criteria are listed 
below. 

• Use of excessively large code segments. If the body of the statement function generates 
a large-sized code sequence, it will not be expanded. This is because large statement 
functions benefit relatively less from the advantages of expansion discussed above. 
Also, expanding large statement functions can cause the calling program to grow to 
an excessive size. The cutoff point is approximately twenty machine instructions; it 
varies depending on data type and operation complexity. 

• Use of external function calls. If the body of the statement function contains a call to an 
external function or another unexpanded statement function, it will not be expanded. 
Again, this is because such functions benefit relatively less from the expansion than 
do other functions. 

• Use of CHARACTER operations. If the function returns a CHARACTER result or 
uses any CHARACTER variables, arrays, operations or arguments, it will not be 
expanded. This is because character operations on VAX destroy the contents of sev¬ 
eral registers and would significantly degrade other optimizations if expanded inline. 

• Incorrect usage. If the actual arguments do not match the formal arguments to the 
statement function in order, number, or data type, it will not be expanded. Some 
usages will generate a warning message, such as a mismatch in the number of argu¬ 
ments. Others will generate correct results if called, but not if expanded. In these 
cases, no expansion is done, but a warning is not given. 

If a statement function is not expanded inline, it degrades other optimizations besides calls 
to itself. In particular, it prevents any local variables used in the statement function body 
from being selected for global analysis. For this reason, you should limit the use of local 
variables in statement functions to those cases that match the criteria described in the 
preceding list. 
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1.3.2.4 Effects of Variable Format Expressions - VAX FORTRAN provides variable format 
expressions (VFEs) for increased flexibility and performance of formatted I/O (see I/O dis¬ 
cussion in Section 1.4.5). Using VFEs is generally preferable to using run-time format 
expressions because it allows the compiler to use the efficient compile-time format inter¬ 
face to the FORTRAN RTL I/O support routines. Using a variable in a VFE, however, does 
prevent it from being selected for global analysis. For this reason, it is a good idea to use a 
variable for just its need in a VFE and nothing else. 

1.4 Speed Optimizations 

Speed optimizations fall into four categories: 

• Removal optimizations — Remove unnecessary operations from the program. 

• Replacement optimizations — Make necessary operations more efficient. 

• Operation-specific optimizations — Apply to certain individual operations. Examples 
and discussion of some of these are given in the section for this topic. 

• I/O optimizations — Reduce I/O system overhead and are controlled by how you set up 
I/O operations in your source program. 

This section addresses these topics, respectively, in Sections 1.4.2 through 1.4.4. 

Being aware of the optimizations discussed in this section may make it easier for you to 
write your programs in a straightforward and general way. In many cases, you could also 
gain the performance benefit of these optimizations by modifying the source program 
directly, as shown by the examples, but this practice often leads to errors and makes the 
program harder to read. 

1.4.1 Effects of Global Analysis on Speed Optimizations 

Global analysis is required for both kinds of speed optimizations, that is, both removal and 
replacement optimizations. 

For removal optimizations, both arrays and variables must be analyzed. The upper limit 
on the number of variables and arrays that the compiler will analyze for these optimiza¬ 
tions is 128. If the program unit contains more variables and arrays than that, the com¬ 
piler chooses the 126 most heavily used for global analysis. It then treats all remaining 
local variables and arrays as if they were a single array and all remaining COMMON vari¬ 
ables and arrays as if they were a different, single array. 

For replacement optimizations, only variables need be analyzed, not arrays. However, 
replacement optimizations require additional analysis beyond that required for removal 
optimizations. For this reason, the compiler separately selects a set of variables for this 
additional analysis. The upper limit on the number of variables for this kind of analysis is 
32. Most replacement optimizations involve the use of the VAX general-purpose registers. 
Because the number of registers available for use by optimizations is 13, selecting addi¬ 
tional variables beyond 32 would not generally result in more replacement optimizations. 
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The selection criteria for variables used for this analysis is more restrictive than those for 
removal optimizations. In particular, variables whose usage prevents them from being 
loaded into registers are not selected. These include variables used in common blocks, 
variables used in EQUIVALENCE statements, variables declared volatile, variables used 
in statement functions that do not get expanded in-line, and variables used in variable 
format expressions (see Section 1.3.2). 

1.4.2 Removal Optimizations 

Removal optimizations generally have a greater effect on program performance than that 
of replacement optimizations. This is because they remove run-time operations from the 
program entirely. Many of the removal optimizations performed by the compiler are 
described in the subsections that follow. 

1.4.2.1 Compile-Time Operations - The compiler attempts to perform as many operations 
as possible at compile time. This removes them entirely from the object program. 

Constant Operations 

In particular, the compiler performs the following computations on expressions involving 
constants (including PARAMETER constants) at compile time. 

• Negation of constants — constants preceded by unary minus signs are negated at com¬ 
pile time. For example: 

X = -10.0 

is compiled as a single move instruction. 

• Arithmetic operators on integer ; real, and complex constants — expressions involving 
+ or / operators are evaluated at compile time. For example: 

Unoptimized Code Optimized Code 

PARAMETER (NN=27) PARAMETER <NN=27) 

I = 2*NN + J I = 54 + J 

Evaluation of some constant functions and operators is performed at compile time. In 
particular, the CHAR, ABS, MAX, MIN, and MOD functions of constants, concatena¬ 
tion of string constants, and logical and relational operations involving constants are 
performed at compile time. 

• T^ype conversions of constants — lower-ranked constants are converted to the data type 
of the higher-ranked operand at compile time. For example: 

Unoptimized Code Optimized Code 

X = 10* V X = 10.0 * Y 

• Array address calculations — array address calculations involving constant sub¬ 
scripts are simplified at compile time whenever possible. For example: 

DIMENSION 1(10*10) 

1(1*2) = 1(4*5) 
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is compiled as a single move instruction. 

Initialization of Argument Lists 

Argument lists are initialized at compile time whenever the address of the argument can 
be determined at compile time. For example: 

CALL SUBX(M> A(3 >4) ) 

is compiled as a single CALL instruction. See Section 3.1.1 for additional information 
about argument lists. 

Delaying Optimizations 

The compiler eliminates operations that can be shown at compile time to have no effect, or 
that can be transformed so as to be unnecessary. 

For example, there are a number of operations that can be mathematically proven to leave 
the result unchanged. These operations are eliminated. For example: 

x = Y * l. o 

is compiled as a simple move instruction. It is also possible to eliminate more complicated 
combinations, for instance: 

X = Y * -1*0 

is compiled as a move negated instruction. 

Another example of operations that can be shown to have no effect at compile time 
involves some unary minus and .NOT. operations. These operations can also be delayed 
until they can be proven to be unnecessary, and if so, they are eliminated. In the following 
example, both negations are eliminated. 

X = -Y * -Z 

1.4.2.2 Flow Boolean - In general, it is not necessary to actually generate a temporary 
logical variable with the value of the logical expression used in an IF statement. In most 
cases, the compiler avoids generating these unnecessary temporary variables. Instead, it 
makes use of compare operations and condition codes that are a more efficient means of 
controlling program behavior. 

1.4.2.3 Compound Logical Expressions in IF Statements - Unnecessary operations in com¬ 
pound logical expressions in IF statements can often be avoided. Many compound logical 
expressions do not need to be evaluated completely and a partial evaluation suffices to 
determine the final outcome. For example, if el in the following expression has the value 
.FALSE., e2 is not evaluated: 

IF (el .AND. e2) GO TO 20 

Effectiveness 

In addition, the compiler changes the order of evaluation of the components of the expres¬ 
sion to do the simplest first. Thus, in the example, 
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IF <A(I*J) 4 GT♦ B(M»N) ,0R, X ,GT, Y) GO TO 20 

the subexpression X .GT. Y is evaluated first, and if it evaluates .TRUE., the array element 
comparison is not performed. 

Correctness 

The FORTRAN 77 language prohibits programs that depend on the order of evaluation of 
their subexpressions. This dependency can arise from the occurrence of side effects within 
compound logical expressions in IF statements, as described previously. Thus, if the fol¬ 
lowing statement was used repetitively, 

IF (RAN(K) 4 GT 4 0*5 .AND, A .GT. B) GO TO 20 

the function RAN may be called on some executions and not others because the compiler 
will evaluate A .GT. B first and avoid the RAN call if it evaluates .FALSE. Because the 
RAN call has a side effect on its argument, different sequences of random numbers will be 
generated depending on the sequence of values of A and B. This will have an effect on the 
control flow of the program and, as a result, different answers may be generated (that is, 
answers different from those that would be generated if RAN(K) were always evaluated). 

For this reason, you should always explicitly reference functions with side effects prior to 
their use in logical expressions. For example, the program above could be made to conform 
to the language rules as follows: 

RANOAL = RAN(K ) 

IF (RANOAL .GT. 0.5 .AND. X .GT. Y) GO TO 20 

1.4.2.4 Common Subexpression Elimination - The same subexpression often appears in 
more than one computation within a program unit. For example: 

A = B*C + E*F 
H = A + G - B*C 
IF <(B*C)-H> 10 >20 ,3 0 

In this code sequence, the common subexpression B*C appears three times. If the values of 
the operands of this subexpression do not change between computations, its value can be 
computed once and the result can be used in place of the subexpression. Thus, the sequence 
shown above is compiled as follows: 

t = B*C 
A = t + E*F 

H = A + G + t 

IF ( (t ) -H) 10,20*30 

As you can see, two computations of B*C have been removed. This optimization is called 
common subexpression elimination. 
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Of course, you could have optimized the source program yourself to avoid the redundant 
calculation of B*C. The following example shows a more significant application of this 
kind of compiler optimization. In this case, you could not reasonably modify the source 
code to achieve the same effect. Without optimization, the statements 

DIMENSION A < 25 *25) * B(25 ,25) 

A<I»J> = B(I»J) 

can be compiled as 

tl = (J-1)*25+I 
12 = (J- 1)*25+I 
A ( 11 ) = B ( 12 ) 

Variables tl and t2 represent equivalent expressions. The compiler eliminates this redun¬ 
dancy by producing the following optimization: 

t = (J-1)*25+1 
A ( t ) = B(t ) 

1.4.2.5 Code Motions - Execution speed is enhanced by taking invariant computations 
out of loops. This optimization is called loop hoisting. Loop hoisting can be unconditional or 
conditional. 

Unconditional Loop Hoisting 

If the compiler detected the following sequence, 

DO 10 t 1 = 1 ,100 
10 F = 3♦0 * 0 * A(I) + F 

it would recognize that the subexpression 3.0*Q has the same value each time the loop is 
executed. Thus, it would change the sequence to 

t = 3*0*0 
DO 10 1=1t100 
10 F = t*A( I ) + F 

This moves the calculation of 3.0*Q out of the loop, thus saving 99 multiply operations. 

Conditional Loop Hoisting 

Moving code out of loops is possible even if there is code that is not always executed in each 
iteration of the loop. For example: 

DIMENSION A(25>25)> B(25>25) 


10 


DO 10 1=1>25 

IF (I ♦GT♦ K) THEN 

A( I #J) = A(K ,J) 

ELSE 

B(I »J) = B(K tJ) 

END I F 
CONTINUE 


In this case, the subscript computations can be moved out of the loop, and the preceding 
sequence is compiled as follows: 
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10 


tl = (J- 1)*25 
t2 = tl+K 
DO 10 1 = 1 ,25 
IF (I ♦GT♦ K> THEN 

A ( 11 + I ) = A ( 12 ) 

ELSE 

B ( 11 + I ) = B ( 12 ) 

END I F 
CONTINUE 


This example shows that all of the multiplications and half of the additions used in array 
addressing computations are eliminated from the loop by conditional hoisting. 


1,4.2.6 Value Propagations - The compiler keeps track of the values assigned to variables 
and traces the values to all of the places that they are used. If it is more efficient to use the 
value than the variable, the compiler makes this change. This optimization is called value 
propagation and can have several beneficial effects. 

The following sections describe the propagation of variables, the propagation of constants, 
and the elimination of variables. 

Propagation of Variables 

One beneficial effect is to remove unnecessary memory references from the program. For 
example: 

Unoptimized Code Optimized Code 

A = Z 

X = F(X) + A X = F(X) + Z 

Note that the operations involving both the storage of Z into the variable A and the 
retrieval of A from memory have been removed from the program. 

Propagation of Constants 

Additional improvements are possible when the quantity being propagated is a constant 
known at compile time. This special case is called constant propagation. 

Constant propagation has several benefits: 

• It allows run-time operations to be replaced with compile-time operations, for 
example: 

Unoptimized Code Optimized Code 

PI = 3*14 PI = 3*14 

PI0VER2 = PI/2 PI0UER2 = 1*57 

In this case, the divide operation has been removed from the program. This process is 
repeated and further constant propagations are often possible. 
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• It allows comparisons and branches to be avoided at run time. For example: 

Unoptimized Code Optimized Code 

I = 100 I = 100 

IF (I ♦LT♦ 1) GO TO 100 A(100) = 3*0*Q 

A(I) = 3*0*0 

• It can, in some cases, even lead to the elimination of several statements. For example: 

Unoptimized Code Optimized Code 

I = 100 I = 100 


IF (I .GT. 1) GO TO 10 10 Y = 3*0*0 

M = N* J 
K = M + I 
10 Y = 3*0*0 

The statements immediately following the test are removed because they can never 
be executed. 


In addition to propagating constant values from program assignments, the compiler 
propagates constant values from DATA statements. When compiling subprograms, the 
compiler analyzes the program to ensure that this is done correctly if the subroutine is 
called more than once. For example: 


Unoptimized Code 

SUBROUTINE SUBA(K »M»N> 
DATA I»J/3 *4/ 

M = I * 4 
N = J * 4 

IF (K *GT* 0) J = K 


Optimized Code 

SUBROUTINE SUBA(K ,M»N> 
DATA I »J/3 i4/ 

M = 12 
N = J * 4 

IF (K *GT. 0) J = K 


The value of 3 is propagated from the DATA initialization of I, eliminating a multiply 
operation. The value of 4 for J is not propagated because it may not retain its initialization 
after the first call to SUBA. 

Variable Elimination 

Occasionally, value propagation can eliminate the need for a variable entirely. You can 
determine whether a variable has been eliminated from the program by looking at the 
storage map section of the compiler output listing. If the memory address of the variable is 
given as it has been eliminated. 

1.4.2.7 Dead Store Elimination - Sometimes a variable is assigned a value, but that value 
is never used in the program. In this case, the assignment is eliminated as well as any 
calculation that the assignment requires. For instance: 
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Unoptimized Code Optimized Code 

X = Y*Z 

♦ . ♦ X = A<I tJ) * PI 

X = A<I tJ) * PI 

If the first assignment to X is never used at all in the program, it is removed. If this causes 
previous assignments to Y and Z in the program to be unnecessary, they are removed also. 
This process is continued until there are no unnecessary operations left. 

NOTE 

Some programs used for performance analysis contain such unnecessary opera¬ 
tions. When attempting to measure the performance of programs compiled with 
VAX FORTRAN, you should not use such programs because they will give 
unrealistic results. Programs used for performance evaluation should always 
use their results in output statements or subprogram calls. 


1.4.3 Replacement Optimizations 

Many well-written programs do not contain frequent opportunities for removal optimiza¬ 
tions, as described in Section 1.4.2. So, although these optimizations have a large effect 
each time they are used, they may provide little benefit to your program. On the other 
hand, replacement optimizations usually make only a modest improvement in program 
efficiency each time they are used, but are much more frequently usable. For this reason, 
they can add up to a larger improvement overall than that provided by removal 
optimizations. 

In general, replacement optimizations do not lend themselves well to being illustrated in 
source examples, unlike the removal optimizations discussed previously. Often, replace¬ 
ment optimizations can be described only in technical terms specific to the VAX architec¬ 
ture. For this reason, you should be familiar with the VAX-11 Architecture Reference 
Manual in order to fully understand the material in this section. 

NOTE 

In some examples, the code listed under the heading, “optimized code,” is not the 
exact code that would be generated by the compiler. Actual machine code may 
vary depending on optimizations elsewhere in the program. The examples are 
only intended to help explain the optimizations being discussed. 


The subsections that follow describe the various areas in which replacement optimizations 
take effect. 
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1.4.3.1 Store Delaying Optimizations - The FORTRAN language specifies that expressions 
in assignment statements are to be completely evaluated before the assignment is per¬ 
formed. In most cases, however, the same answer results on VAX if the appropriate 3 oper¬ 
and form of the operation is performed. In these cases, the compiler will use the 3 operand 
form of the operation to eliminate the need for a temporary variable and a separate move 
instruction to put the result into its proper place. For example, the source code 

X = 3*0*0 

results in: 

Unoptimized Code Optimized Code 

MULF3 #3*0» Qt RO MULF3 #3*0 » Q> X 
MOOL RO » X 

1.4.3.2 Register Usage - For most programs, the compiler can generate code that uses the 
VAX general-purpose registers rather than ordinary memory locations. Because opera¬ 
tions using the registers are often much faster than equivalent operations that reference 
memory locations, such programs are much faster than equivalent unoptimized programs. 
The remainder of this section describes the optimizations that make use of the VAX gen¬ 
eral-purpose registers. 

Holding Temporary Operation Results 

The VAX general-purpose registers are most frequently used to hold the values of tempo¬ 
rary results of subexpressions, even if the /NOOPTIMIZE qualifier is used. Registers can 
be used in many other ways to speed up programs, but no more than 13 of them are availa¬ 
ble at any point during the program; as a result, it is important to minimize using them to 
hold expression results. The compiler does this by reordering the evaluation of compli¬ 
cated expressions so as to reuse the same registers as much as possible during the evalua¬ 
tion. It does this by always computing the most complicated subexpression first in an 
operation and then reusing, for the next operation, the registers that are no longer needed. 
For example, the statement 

A = B*C + D*E + F*G 

requires the use of only 2 registers: 

MULF3 C > Bt RO 

MULF3 Et Dt R1 

ADDF2 R1» RO 

MULF3 G t Ff R1 
ADDF3 R1 * RO * A 

Holding Variables 

The compiler uses registers to hold the values of program variables at any time that the 
FORTRAN language does not require them to be in memory. It may hold the same variable 
in different registers during different points in the program. For example: 
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3 ♦ 0*Q 


U = 

X = SIN ( Y ) * U 
0 = PI*X 
Y = COS(Y)*V 

The compiler may choose one register to hold the first use of V and a different register to 
hold the second. Both registers may be used for other purposes in between. Thus, there 
may be points in time when the value of the variable does not exist anywhere. If the value 
of V is never needed in memory at any time, it will be eliminated from the program 
entirely. As with variables eliminated by value propagation, a “**” is printed in the mem¬ 
ory map part of the listing for these variables. 

Indexing into Arrays 

Often variables are held in registers to index into arrays. For example, the statement 
A(I ) = B<J) + C(K) 

results in the following code (in the absence of other optimization effects, such as loops 
involving I, J, or K): 

MOOL If R 1 2 

MOUL K » RO 

MOOL Jf R1 

ADDF3 C-4CR03» B-4CR13# A-4CR123 

Most expressions, however, do not use all different index variables. For example, the fol¬ 
lowing statement is more representative of normal usage: 

A ( K ) = B(K) + C(K) 

In this case, K will be loaded into only one register and will be used to index into all three 
arrays at the same time. The compiler will do this even if K must normally be held in mem¬ 
ory (if K is in shared global common, for instance). The optimized code is: 

MOOL K » RO 

ADDF3 K-4[RO 3 * B-4CR03, A-4CR03 

Using as Base Registers for Arrays and Common Blocks 

In most cases, shrinking the size of the code generated for VAX will also increase the speed 
with which it is executed. Thus, it is important not only to minimize the number of opera¬ 
tions performed, but to use the minimum size for the operand specifications involved in the 
operations. The FORTRAN compiler uses the general purpose registers, called base regis¬ 
ters, for this purpose. Reducing the size of operand specifications can often be accomplished 
by loading a register with either the memory address of the operand or an address close to 
the operand. Then, the operand specifier can use a small offset, 0,1, or 2 bytes, rather than 
a large 4-byte offset that is used when base registers are not used. Base registers are used 
for addressing local variables and arrays, common blocks, and dummy arrays. For exam¬ 
ple, the code 
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COMMON /Cl/ A(10) t B ( 10 ) t C(10) 


A ( I) = B(I) + C(I) 
generates: 

Unoptimized Code 


MOOL I» RO 

ADDF3 C-4[R0] t B-4CR0]» A-4CR0] 

Optimized Code 

MOUAL A> R12 


MOUL I, RO 

ADDF3 C-4CR12)CR03» B-4<R12>CR03> A-4<R12)CRO3 

In the unoptimized case, the ADDF3 takes 19 bytes. In the optimized case, it takes seven 
bytes. 


1.4.3.3 Using Autoincrement and Autodecrement Address Modes - In order to reduce both 
memory requirements and execution time, the compiler also uses base registers in an addi¬ 
tional way. Specifically, the compiler can make use of the autoincrement and autodecre¬ 
ment register modes available to operand specifiers in the VAX architecture. The compiler 
uses these modes when it detects that a pointer to an array can be updated at the same time 
that the array is referenced. Take a simple summing loop, for example: 

DO 10 K = 1 >1000 
10 X = X + A(K) 


Unoptimized Code 


Optimized Code 


MOOL 
L$1: MOOL 
ADDF2 
AOBLEQ 


#1 t K 
K , RO 

A - 4 C R 0 ] > X 
#1000» K t L$1 


MOOL 
MOOAL 
L$ 1 : ADDF2 
AOBLEQ 


#1 > K 
A > RO 
(RO)+ * X 
#1000» K t L$1 


In general, the array reference will need to be recomputed each time around the loop. This 
process can be greatly speeded up if the base register pointing to the array can be updated 
each time the array is referenced so that it always points to the correct element. The 
autoincrement and autodecrement address modes can accomplish this. 


HINTS 

There are some requirements that must be met before the autoincrement or 
autodecrement modes can be used, however. 

• The array index expressions cannot be too complicated; they must be sim¬ 
ple additions or subtractions of the loop index variable with expressions 
that do not change within the loop. 
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• The successive array references within the loop must occur according to the 
order of subscript progression, as defined by the description of arrays 
within Programming in VAX FORTRAN. In general, this means that the 
leftmost subscript should vary the fastest (that is, be in the innermost 
loop). 

• The increment value of the loop must be a constant (a PARAMETER con¬ 
stant can be used). 

• The compiler can use autoincrement even if the loop steps by more than one 
increment at a time. However, there must be at least as many array refer¬ 
ences within the loop as the increment value. For instance, autoincrement 
cannot be used for the following loop: 

DO 10 1=2 >100 *2 
10 X = X + B < I ) 

Autoincrement cannot be used because the loop contains only one reference 
to B; this allows only one opportunity to update the base register, and 
autoincrement requires two opportunities. This means that you can freely 
use “loop unrolling” techniques, for reducing loop overhead, without sacri¬ 
ficing efficiency of array index calculation. 


The following example shows a loop (unrolled) that results in a substantial speedup 
because of the use of autoincrement address modes for the array references: 


Source Code: 

DO 50 I = MP1>N»4 

DY( I ) = DY(I) + DA*DX <I) 

DY(I + 1) = DY(I + 1) + D A * D X (I + 1) 

DY<I + 2) = DY<I + 2) + D A * D X(I + 2) 

DY(I + 3) = DY(I + 3) + D A * D X(I + 3) 

50 CONTINUE 


Optimized Code: 

MOUL 
MOOAF 
MOUAF 
L$1: MULF3 

ADDF2 
MULF3 
ADDF2 
MULF3 
ADDF2 
MULF3 
ADDF2 
ACBL 


MP1 

> I 



DX ( 

I ) t 

R3 


DY ( 

I ) , 

R4 


( R3 

)+ » 

DA : 

> R5 

R5 » 

<R4) + 


( R3 

) + t 

DA : 

> R5 

R5 > 

<R4) + 


( R3 

)+ , 

DA : 

, R5 

R5 , 

<R4) + 


( R3 

)+ , 

DA : 

, R5 

R5 » 

(R4) + 


N » 

#4 > 

I > 

L$ 1 
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In this example, each of the array references in the loop uses an autoincrement mode. Note 
that the successive references to the arrays use the same or increasing array indexes. This 
is recommended because it allows the most autoincrement references and the smallest off¬ 
set values. The compiler is, however, equally effective at optimizing loops in which the 
array indexes are successively decreasing rather than increasing. In the case of decreasing 
array indexes, autodecrement address modes are used and you should use monotonically 
decreasing array indexes for maximum effectiveness. It is even possible to use both modes 
in the same loop, but this requires the compiler to use multiple registers for indexing 
because the same register cannot be used for both autoincrement and autodecrement at 
the same time. 

1.4.3.4 Strength Reduction - If autoincrement or autodecrement address modes cannot be 
used for array addressing in a loop, it is still possible for part of the addressing computa¬ 
tion to be speeded up. Because the technique for doing this involves introducing an add 
operation in place of a multiply, it is called “reduction in operator strength,” or simply 
“strength reduction.” Basically, the technique involves using an add instruction to update 
an array pointer each time around the loop instead of re-computing the array index when 
it requires a multiply. For example: 

REAL*8 A(25#100) 


0 = 0 

DO 10 1=1#100 
10 0 = 0 + A < K # I ) 


Unoptimized Code 

Optimized Code 


CLRD 

0 


CLRD 

0 

MOUL 

#1 # R12 


MOUL 

#1 # R3 

L$l: NULL 

#25 # R 1 2 # RO 


MOUL 

K # R 1 2 

ADDL2 

K # RO 


MOUAD 

A-8CR123 

ADDD2 

A - 2 0 8 [ R 0 ] # 0 

L$ 1 : 

ADDD2 

(R4) # 0 

AOBLEQ 

#100# R12 * L$ 1 


ADDL2 

#200# R4 




AOBLEQ 

#100# R3 


In the preceding example, the unoptimized code sequence computes successive values of 
A(K,I) by using MULL3 and ADDL2 operations and a context index register mode for the 
ADDD2. In the optimized code sequence, the MULL3 and ADDL2 are replaced by a single 
ADDL2 that updates the pointer into A. It also allows the reference in the ADDD2 instruc¬ 
tion to use the shorter, indirect mode instead of context indexing. 

1.4.3.5 Tradeoff Policy - In a large program, there are usually more quantities that would 
benefit from being in registers than there are registers to hold them. In this case, the com¬ 
piler must apply tradeoffs in determining how to use the registers. In general, the compiler 
tries to use the registers for temporary operation results first, including array indexes; 
then variables; then base registers; then all other usages. The decision criteria are compli¬ 
cated, however, and this hierarchy may not always be followed. 
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In general, finding the best choice of register usages for a given program requires a very 
large amount of computation. Essentially, the only way to do this is to try all of the meth¬ 
ods and choose the best. However, if this method were followed, it would lead to unaccept¬ 
ably long compile times. For this reason, the compiler uses heuristic algorithms, and a 
modest amount of computation, to attempt to find a good usage for the registers. Thus, the 
compiler will often not choose the best way to apply the registers, but it will normally 
choose a usage that is significantly faster than that of an unoptimized program. 


1.4.3.6 Block Moves and Block Initializations - Occasionally, statements in loops are well 
adapted to the use of special VAX instructions for performing a large amount of data move¬ 
ment at once. Typically, the data movement operations involve assignment of one array to 
another or filling an array with a uniform initial value. These usages take advantage of 
the VAX MOVC3 and MOVC5 instructions, respectively. When the compiler detects these 
usages, it generates the appropriate special VAX instruction, for example, the loop: 

DO 10 1=1>1000 
10 A(I) = B(I) 

results in: 


Unoptimized Code 


Optimized Code 


MOOL 
L$1: MOOL 
MOOL 
AOBLEQ 


#1, I M00C3 

I > RO MOOL 

B-4CR0H > A-4 C R 0] 

#1000 > I > L$1 


#4000 > B > A 
#1001> I 


Another typical usage is to initialize an array with zeros, for instance: 

DO 10 1=1>1000 
10 A(I) = 0•0 


results in: 


Unoptimized Code 


Optimized Code 


L $ 1 : 


MOOL #1> I 

MOOL I > RO 

MOOL #0.0> A-4 C R 0] 

AOBLEQ #1000> I> L$1 


M00C5 #0> <SP)> #0> #4000 > A 

MOOL #1001> I 


HINTS 

Some requirements must be met before the compiler can use these special 
instructions. 

• The array addresses used in the loop must be uniformly increasing by one 
element on each iteration of the loop. 

• The arrays involved must not appear in, or have any dependencies in, the 
loop other than their assignment or initialization. 
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• The arrays must not overlap in memory. The most common overlap cases 
are the assignment of one dummy array to another, or to or from an array in 
COMMON. These overlap cases may occur in some calls but not others. 
Because the potential exists, the optimization cannot be performed in these 
cases. 

As long as these requirements are met, even subsections of arrays can be assigned using 
MOVC3, for example: 

DOUBLE PRECISION A(1000 >1000) t B(1000»1000) 

INTEGER M(1000) t N(1000) 

DO 10 1=201>800 
A(1-200 »J) = B(1+200 »K) 

10 M<1-200) = N<1+200) 

will assign, with a single MOVC3 instruction, 600 elements of B starting at B(401,K) and 
ending at B(1000,K) to elements of A starting at A(1,J) and ending at A(600,J). It will also 
assign N(401) through N(1000) to M(l) through M(600) using a different MOVC3 instruc¬ 
tion. Any number of such assignments in the same loop can be replaced by MOVC3 
instructions as long as the assignments do not have dependencies on each other. 

There are additional requirements when using the MOVC5 instruction for initialization of 
arrays. Floating point and complex arrays can only be initialized to 0.0 and (0.0,0.0), 
respectively, with this instruction. Integer and logical arrays can be initialized with 0 or 
- 1 . 

1.4.3.7 Locality Of Reference - The virtual memory architecture of the VAX series of com¬ 
puters allows the use of very large arrays without the need for overlays or for large 
amounts of physical memory equivalent to the size of the program. This is accomplished by 
storing the pages of memory on disk when they are not being used, and then copying them 
into memory when their values are needed or they are being assigned. The machines are 
designed to make this copying activity totally transparent and very fast. Usually, it is so 
fast that it is not a significant contributor to the running time of a FORTRAN program. 

Most programs do not reference memory addresses randomly. They usually reference 
groups of addresses that are close to each other (that is, local). This typical clustering of 
address references is called locality of reference. 

One of the ways that the VAX series of computers makes the required copying efficient is 
by taking advantage of locality of reference. Whenever a given page of memory requires 
copying, the system also copies the pages near it, which reduces the need for future copies. 
This technique is called page clustering. You can improve the speed of your programs by 
maximizing the amount of page clustering. This can be done most easily by avoiding refer¬ 
ences to memory at widely scattered addresses. 
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Order of Subscript Progression with Array References 

In FORTRAN programming, certain coding practices defeat the page clustering technique 
and greatly increase the amount of copying to and from disk. The most common of these 
inefficient practices is the referencing of arrays in a order that does not correspond to the 
order of subscript progression. For example: 

DIMENSION A<1000,1000) , B<1000,1000) 

DO 10 J=1,1000 
DO 10 1=1,1000 
10 A(I»J) = B<I,J)*X 

is very efficient on VAX because each reference to A and B is adjacent in memory to the 
previous one, thus allowing page clustering to drastically reduce the number of disk copy 
operations. On the other hand, the superficially similar loops 

DO 10 1=1,1000 
DO 10 J=1,1000 
10 A<I ,J) = B(I ,J)*X 

are much less efficient on VAX than the previous loops. This is because each reference to A 
and B is about 1000 elements away from the previous reference. In this case, the running 
time of the program will be dominated by the copying of the arrays to and from the system 
disk. 

For this reason, when you are trying to improve program performance, it is important to 
understand the concepts of locality of reference, page clustering, and the order of subscript 
progression of arrays. Then, when you identify an inefficient program with excessive page 
copying, you will be able to eliminate the usage that is causing the problem. 

1.4.4 Operation-Specific Optimizations 

A number of speed optimizations do not fall into the categories described previously. These 
are described briefly in this Sections 1.4.4.1 through 1.4.4.6. In general, they are ways of 
implementing specific FORTRAN usages to take better advantages of the VAX 
architecture. 

1.4.4.1 Constants as Code Literals - Constants used in operations are most often inserted 
into the executable object code directly as literal operand specifiers. For example, the 
source code 

I = 14 

results in: 

Unoptimized Code Optimized Code 

K$ 1: .LONG 14 MOOL #14 , I 

MOOL K $ 1 , I 
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1.4.4.2 JSB for Floating Math Functions - Optimized calling sequences are used for the 
REAL*4, REAL*8, and REAL* 16 versions of some intrinsic functions. For example, the 
source code 

X = SIN(Y) 
results in: 

Unoptimized Code Optimized Code 

CALLG arglist, MTH$SIN MOOF Y » RO 

JSB MTH$SIN_R4 

1.4.4.3 Code Alignment - Labels used as the objects of frequent branch instructions are 
aligned on longword boundaries to improve the speed of the branch operations. This 
optimization results in NOP instructions in the generated code. These will generally 
appear at loop tops and for labels generated by the compiler to implement ELSE or ELSE 
IF constructs. 

1.4.4.4 SINCOS - When the SIN and COS functions (or SIND and COSD functions) are 
both referenced using the same argument, an optimized calling sequence is used that com¬ 
putes both using a single call. 

1.4.4.5 Mixed Real/Complex - Operations on COMPLEX data types are optimized if the 
other operand is REAL. Normally, such an operation is performed by converting the REAL 
to a COMPLEX and then performing the operation using the two COMPLEX quantities. 
The optimization avoids the conversion and performs a simplified operation. The compiler 
performs this optimization on the +, -, and * operations if either operand is REAL, and on 
the / operation if the right operand is REAL. For example, the source code 

COMPLEX A, B 
B = A + R 

results in: 

Unoptimized Code Optimized Code 

MOOF R * RO ADDF3 R» A> B 

MOOF no t R1 MOOF A + 4* B + 4 

ADDF3 RO * A» B 
ADDF3 R1 t A + 4 t B + 4 

1.4.4.6 Peephole Optimizations - The final code is examined on an instruction-by-instruc- 
tion basis to find operations that can be replaced by shorter, faster operations. For exam¬ 
ple, the source code 

A = 0*0 

results in 

Unoptimized Code Optimized Code 

MOOF #40 » A CLRF A 
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The two most common peephole optimizations are test elimination and conversion of oper¬ 
ations from a 3 operand form to a 2 operand form. 

These optimizations are described in the remainder of this section. 

Test Elimination 

IF statements can frequently be optimized when the variables used in their test conditions 
are computed immediately before the IF statement. For example: 

I = M*N 

IF (I ♦ GT ♦ 0) THEN 

In this case, because the value of I is already indicated by the VAX condition codes at the 
time the IF statement is executed, it does not need to be compared with zero explicitly. 
When the compiler detects this situation, it eliminates the compare operation. 

Conversion of 3 Operand Form to 2 Operand Form 

Many VAX arithmetic and logical operations exist in both 2 operand and 3 operand forms. 
The 3 operand forms are generally used because they often prevent the need for MOV 
instructions (see Section 1.4.3.1). However, in many cases in which both the input and out¬ 
put operands are the same register or memory location, the 2 operand form can be used 
instead. The methods used to choose locations for temporary operation results are 
designed to take advantage of this possibility. The 2 operand form has advantages in both 
execution time and memory space. For example, the source code 

A = A + B 

results in 

Unoptimized Code Optimized Code 

ADDF3 B » A » A ADDF2 B » A 

1.4.5 Improving Performance of I/O Operations 

Many FORTRAN programs spend more time and resources performing input and output 
operations than they spend performing computations. In these programs, making the I/O 
operations more efficient is more worthwhile than making the computations more effi¬ 
cient. This section discusses some techniques that you can use to make your I/O operations 
more efficient. 

1.4.5.1 Using Unformatted I/O - FORTRAN formatted input and output operations are 
often compute bound. That is, they often spend as much time converting the input charac¬ 
ters into internal form and the internal form to output characters as they do actually per¬ 
forming the data transfers to and from the output device. For this reason, you should limit 
your use of formatted I/O to those situations in which a person must provide input or 
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examine the output. In cases where the input comes from another program or where the 
output is processed by another program, you should use unformatted I/O instead of format¬ 
ted I/O. 

For example, for an array declared: 

REAL A(25*25) 

the use of an unformatted WRITE, such as: 

WRITE (7) A 

is much more efficient than a formatted WRITE, such as: 

WRITE (7 >100) A 
100 FORMAT (25(' / #25F5.21)) 

Using unformatted I/O has several benefits: 

• It minimizes the CPU resources needed to perform the I/O operation because it avoids 
the translation to and from internal form. 

• For floating point data, it is more accurate because it avoids a roundoff error on both 
input and output. 

• It makes more efficient use of the capabilities of the I/O devices because it allows more 
data to be transmitted in a single operation. 

1.4.5.2 Using the OPEN Statement’s RECORDTYPE Keyword - The default record type for 
FORTRAN unformatted I/O is 'SEGMENTED 1 . Each record is broken up into chunks 
called segments, and the I/O is performed on the segments rather than the records. This is 
not the most efficient way to perform unformatted I/O, but is used because it is the only 
way that works regardless of the size of the records. 

For this reason, you can often significantly improve the speed of the unformatted I/O by 
using 'FIXED' or 'VARIABLE' record type. You should always use 'FIXED' record type 
when the size of the records you are writing is always the same. This allows the I/O subsys¬ 
tem to write exactly the data in your records; no space is wasted and no extra processing is 
needed. 

If your records are not all the same size, you will still benefit by the use of the 'VARIABLE' 
record type. This type requires the I/O subsystem to append a length word at the beginning 
of each record and to provide an additional level of buffering beyond that required for 
'FIXED' record type. This is still better than 'SEGMENTED' type, which requires addi¬ 
tional processing and buffering for each segment, as well as for each record. 

1.4.5.3 Avoiding Run-Time Formats - When performing formatted I/O, two computation 
steps are required for each format string used. 

• First, the format string must be parsed to determine exactly what kind of formatting 
is required. 

• Second, each format code is matched with a corresponding data element from the I/O 
list of the program’s I/O statement and the appropriate translation performed. 
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When run-time formatting is used, both of these steps must be performed each time the I/O 
statement is executed. Run-time formatting is required when the format specifier in the 
I/O statement is the name of an array, an array element, or a non-constant character 
expression. 

The compiler avoids the first, parsing, step of the formatting process when you do not use 
run-time formatting. It parses the FORMAT string at compile time and reduces it to a 
compact internal form that needs little processing at run-time to determine how each data 
item is to be translated. 

The use of run-time formats should be minimized. In many cases, the use of variable for¬ 
mat expressions can replace the use of run-time formats. Variable format expressions 
allow you to vary the exact format specification at run time while retaining the perform¬ 
ance advantages of compiler preprocessing of FORMAT statements. 

1.4.5.4 Using the BACKSPACE Statement - The use of the BACKSPACE statement should 
be avoided. The backspace operation is not directly supported on most VAX I/O devices, 
including magnetic tape drives, and therefore must be simulated by rereading the input 
file from the beginning. This simulation uses extra buffering to avoid rereading the input 
file with every BACKSPACE statement but is less efficient than using a direct access read 
when reading a disk file. 

If a reread capability is required, it is more efficient to read the record into an internal file 
and read the internal file several times than to read and backspace the record. 

1.4.5.5 Using OPEN Statement Keywords to Control I/O - You can use the BLOCKSIZE and 
BUFFERCOUNT keywords in an OPEN statement in order to enhance the efficiency of 
I/O operations. 

• BLOCKSIZE keyword 

One of the ways to reduce I/O overhead when you are using sequential access mode is 
to transfer larger blocks of data with each I/O operation. In this way, you can take 
advantage of the high data transfer rates of the I/O devices while minimizing the per- 
operation computational overhead. In order to transfer larger blocks of data, use the 
BLOCKSIZE keyword when opening the file. See Section 13.1.4 in Programming in 
VAX FORTRAN for more information on the use of the BLOCKSIZE keyword. 

• BUFFERCOUNT keyword 

Often, you can improve the total execution time of a program by overlapping some of 
the computation with the I/O operations. The VAX Record Management Services 
(used by the VAX FORTRAN I/O system) does this automatically by the use of multi¬ 
ple buffers when performing I/O operations. The use of multiple buffers allows the 
program to be processing one buffer while the I/O system is reading into, or writing 
from, another. You can control the use of multiple buffers in several ways, most easily 
by using the BUFFERCOUNT keyword when opening a file. See Section 13.1.5 in 
Programming in VAX FORTRAN for more information on the use of the 
BLOCKSIZE keyword. 
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The following example illustrates the effect on the elapsed time of different values of 
BLOCKSIZE and BUFFERCOUNT on a typical VAX-11 configuration. The example gives 
the relative elapsed CPU time for a program that writes and reads a 1000-element REAL 
array 100 times on a VAX-11/780 The program has the following OPEN statement: 

OPEN (UN IT =1 > ST ATUS = 7 NEW 7 t 

1 F0RM = "UNFORMATTED' t RECORDTYPE='FIXED' t 


RECL=1000t 

BLOCK SIZE = 

I BLK » 

BUFFERC0UNT= 


BUFFERCOUNT= 

BLOCKSIZE = 

1 

2 

3 4 

4000 

1.00 

1.00 

.99 .99 

8000 

.69 

.67 

.67 .66 

12000 

.58 

.54 

.53 .53 


As the example illustrates, you can reduce the elapsed time significantly by choosing the 
number and size of I/O buffers appropriately. However, because the optimal values are 
highly application dependent, you should experiment to determine which values produce 
the best results for any given program. 

The OPEN and CLOSE statements provide explicit control over I/O devices and files, as 
illustrated in the following examples. 

• The following statement allocates space for a file when the file is opened, a more effi¬ 
cient method than that of extending the size of the file dynamically. 

OPEN (UNIT =1 » STATUS= 'NEW ' t INITIALSIZE = 200) 

• The following statement specifies a large blocking factor for I/O transfers. If the file is 
on magnetic tape, the physical tape blocks are 8192 bytes long; if the file is on disk, 16 
disk blocks are transferred by each I/O operation, thus enhancing I/O performance 
(but requiring more memory). 

OPEN < UN IT = 3 t STATUS= 7 NEW ' t BLOCKSIZE=8192) 

• The following statement creates a file with implicit carriage control. Because the first 
character of each record is not used for carriage control, it can contain actual data. 

OPEN (UN IT = 2 » ST ATUS= 'NEW 7 t FQRM= 7 FORMATTED 7 * 

1 CARR IAGEC0NTR0L= 7 LIST 7 ) 

1.4.5.6 Using Alternative 1/0 Methods - When performance requirements call for faster I/O 
operations than can be achieved using standard FORTRAN I/O operations or when you 
need to use special features of the VAX I/O system that are not supported in the FORTRAN 
language, you can use alternative I/O methods. However, these alternative methods are 
not recommended unless you need them because their use makes your program nonstan¬ 
dard and will thus degrade your ability to transport it to other computer systems. 

The VAX/VMS I/O architecture has several levels, the highest level being the language 
support routines in the VAX Run-Time Library. These language support routines are 
described in the RTL Language Support Reference Manual. These routines in turn call the 
general I/O routines of the VAX Record Management Services (RMS) package, which are 
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used for performing I/O by all DIGITAL-supported VAX native-mode language processors. 
VAX RMS routines are described in the VAX Record Management Services Reference 
Manual. 

Often, you can access special features of RMS simply by using a USEROPEN routine. The 
USEROPEN keyword of the OPEN statement is used to specify the address of a user-writ¬ 
ten routine that will be called by the RTL I/O support routines instead of actually perform¬ 
ing the RMS OPEN operation directly. Your USEROPEN routine can then modify the 
RMS control structures to access RMS features not directly supported by OPEN statement 
keywords. The use of the USEROPEN keyword is described in Chapter 4. 

You can also call the RMS I/O service routines directly from your FORTRAN program. To 
do this, you will need to become familiar with how to set up and manipulate the large data 
structures used by RMS in its service calls. These structures are called the File Access 
Block (FAB), Record Attributes Block (RAB), Extended Attributes Block (XAB), and File 
Name Descriptor Block (NAM). Refer to Section 3.3 for information on how to call VAX 
system service routines from FORTRAN programs. Refer to Chapter 4 for more informa¬ 
tion about calling VAX RMS services. 

The lowest level of I/O services on VAX/VMS is the QIO level. This level specifies the 
actual operations that are to be performed by the peripheral devices. The QIO services are 
also callable directly from FORTRAN programs. These services also require data struc¬ 
tures for specifying their arguments. Refer to the VAX/VMS System Services Reference 
Manual and the VAX/VMS I/O Users Reference Manual for more information on how to 
use the QIO services. 

When using these alternative I/O methods, you should never try to use more than one level 
on the same I/O stream at the same time. For instance, you should not mix standard 
FORTRAN read and write operations with direct calls to the RMS service routines for I/O 
on the same file at the same time. Such usage is not supported and cannot be made to work 
without a detailed understanding of every level involved. In addition, DIGITAL reserves 
the right to modify the interfaces used by the compiled code to the FORTRAN RTL I/O 
system, as well as the interfaces from these routines to RMS. 

1.4.5.7 Implied-DO Loop Collapsing - In general, each I/O element in a FORTRAN I/O 
statement is processed by a separate call to the FORTRAN RTL I/O processing routines. 
The computation overhead of these calls is most significant when using implied-DO loops. 
In the case of implied-DO loops, the compiler performs an optimization to reduce this over¬ 
head. In particular, for each innermost implied-DO loop in a nested group, it replaces the 
loop with a single call to an optimized RTL I/O routine that can transmit many I/O ele¬ 
ments at once. This optimization is performed for both formatted and unformatted I/O, but 
is more effective in the case of unformatted I/O. 

Behaviors of Formatted and Unformatted I/O 

In formatted I/O, even though most calls to the RTL I/O support routines have been elimi¬ 
nated, the individual data items still require translating to or from external form. Thus, 
while the implied-DO loops are collapsed for formatted I/O, substantial processing is still 
needed for this type of I/O. 
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For unformatted I/O, on the other hand, collapsing the implied-DO loops often removes 
most of the processing required to perform the I/O. In particular, if the unformatted I/O 
transmits data items that are physically adjacent in memory, a level of buffering is elimi¬ 
nated and efficiency is substantially improved. For example: 

DIMENSION A(200*300) 

READ (5) (<A(I»J)#I = 1 *20 0) »J=1 »300) 

This usage is particularly efficient because the compiler collapses the innermost loop and 
200 elements at a time are read using a single block move operation. Note that efficiency is 
significantly degraded if the loops are nested in the opposite order. This is because block 
moves cannot be done, and locality of reference is destroyed because the natural order of 
subscript progression is not used. 

Source Code Requirements for Optimization 

Certain usages prevent the compiler from collapsing implied-DO loops. You should avoid 
these usages if you intend to take advantage of this optimization. First, when using 
formatted I/O, if the FORMAT statement contains a VFE, the implied-DO loop cannot be 
collapsed. Second, the FORMAT statement must come before the I/O statement in the 
source program. This is because the optimization is performed on the first phase of the 
compiler, so that it is not possible to test for the presence of a VFE in the FORMAT state¬ 
ment if it follows the I/O statement. 

In addition, certain usages of the implied-DO loop control variables prevent collapsing in 
both formatted and unformatted I/O statements. In particular, collapsing cannot be done if 
the control variable is used as a dummy argument or in a COMMON statement, EQUIVA¬ 
LENCE statement, or VOLATILE statement. In addition, the control variable must be of 
INTEGER data type. 


NOTE 

The value of the loop control variable is unpredictable when the I/O statement 
terminates with an end of file or error condition. Your program should only ref¬ 
erence the terminal value of this variable if the I/O statement completes 
normally. 


1.4.5.8 Miscellaneous I/O Optimizations - You can often reduce the execution time of your 
FORTRAN programs by changing your programs to reflect the following observations: 

• Certain kinds of I/O lists can be optimized more effectively than others. For instance, 
an I/O list consisting of a single unformatted element (variable or array) does not 
have to be buffered in the Run-Time Library buffers. Also, implied-DO loops consist¬ 
ing of a single unnested element are transmitted as a single call to the Run-Time 
Library. 
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• To obtain minimum I/O processing, the record length of direct access sequential 
organization files should be a divisor or multiple of the device block size of 512 bytes 
(for example, 32 bytes, 64 bytes, and so on). For relative organization files, RMS adds 
one overhead byte for fixed-length records and three overhead bytes for variable- 
length records, so the record length should be adjusted accordingly 

• If the approximate size of the file is known, it is more efficient to allocate disk space 
when a file is opened than to extend the file incrementally as records are written. You 
can make this allocation using the INITIALSIZE keyword in the OPEN statement. 

1.5 Space Optimizations 

Even though the VAX architecture allows the use of large memory spaces without 
overlays, it is still important to minimize the use of memory. Doing this often results in 
additional speed improvements and generally improves system throughput. The memory 
space optimizations performed by the compiler are described below. These fall into two 
categories: data size and code size. 

1.5.1 Data Size Optimizations 

The compiler optimizes the use of data space by avoiding duplication of quantities requir¬ 
ing space and by eliminating data items that are not actually used by the program. 

1.5.1.1 Constant Pooling - Only one copy of a given constant value is ever allocated mem¬ 
ory space. If that constant value is used in several places in the program, all references 
point to that value. 

1.5.1.2 Argument List Merging - Argument list data structures are built by the compiler to 
describe actual argument lists used by your program. Only one copy of a given actual argu¬ 
ment list is built, even if it is used by more than one CALL or FUNCTION reference. For 
example: 

XYZ = A + FUNC(B tC) 

CALL SUB A ( B tC) 

The argument list (B,C) is allocated only once in memory. 

1.5.1.3 Dead Variable Elimination - Variables whose uses have all been removed by value 
propagation optimizations, or by register usages, are not allocated in memory. In the mem¬ 
ory map section of the compiler output listing, such variables appear with “**” given as 
their memory location. 
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1.5.2 Code Size Optimizations 

The compiler performs several optimizations of the space taken by the object code. These 
optimizations frequently improve execution performance also. 

1.5.2.1 Local Storage Allocation - The allocation of local variables and arrays declared in 
your program (that is, those variables and arrays not in common blocks or dummy argu¬ 
ments) is chosen so as to minimize the offsets from the base register used to address them. 
The VAX instruction modes allow offsets of different sizes (0, 1, 2, or 4 bytes) for exactly 
this purpose. A considerable execution speed advantage can often be achieved by using the 
smallest necessary offset size. 

1.5.2.2 Jump Branch Resolution - In addition to allowing different sizes of operand offsets, 
VAX allows the use of a variety of branch type instructions for controlling the flow of pro¬ 
gram execution. These different branch instructions allow different offset sizes for code 
space optimization. The compiler optimizes the use of these instructions to choose the 
smallest offsets required for each branch in the program. 

1.5.2.3 Dead Code Eliminations - The compiler can sometimes detect that some parts of the 
program will never be executed. In this case, it removes the code entirely. It does this in 
several different ways and in several phases of the compiler. These dead code eliminations 
do not necessarily mean that poor programming practice has been followed. For this rea¬ 
son, no warning messages are given when dead code is eliminated. Often, it is simply the 
result of using PARAMETER constants. 

Code Reordering for Branch Elimination 

The compiler reduces the number of branch type instructions in the program by arranging 
the order in which the statements appear in the machine code. This optimization effec¬ 
tively removes unneeded GO TO operations from the machine code. 

Elimination of Unreachable Code 

Source code that can never actually be executed is said to be dead code. 

For example: 

IF (♦FALSE*> A = B 

In this case, the assignment statement will never be executed. 

Even though the existence of dead code in a program does not generally affect execution 
speed, it does occupy memory space needlessly. It also causes larger offsets to be needed in 
branch instructions that span the dead code. The compiler detects dead code in two ways 
and always eliminates it from the object program. 
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• Lexically detected — warning issued 

The compiler detects dead code first by identifying source statements that cannot be 
reached. For example: 

GO TO 100 
I = J*K 

The assignment statement in this example can never be executed because the GO TO 
statement is unconditional and because the assignment statement has no label that 
can be referenced by a control statement, such as DO or GOTO. When the compiler 
detects such usage, it issues a warning message indicating that the statement cannot 
be reached. 

• Detected by value propagation — no warning 

Sometimes, it is not apparent from the source program that the dead code cannot be 
reached. For example: 

i = 100 

IF (I ♦LT♦ 0) A = B*C 

In this example, the assignment can never be executed because the value of I will 
never be less than 0. When the compiler detects such usage, it does not issue a warn¬ 
ing that the code cannot be reached. 

Elimination of Operations on Dead Variables 

The compiler analyzes the use of selected variables to determine if they have any effect on 
the output of the program unit. If they do not, they are called dead variables. The compiler 
optimizes both speed and space by eliminating all operations on dead variables. 

1.6 Compiler Optimization Example 

The example in this section illustrates many of the optimization techniques used by the 
VAX FORTRAN compiler. The first part (Figure 1-1) shows a complete FORTRAN subrou¬ 
tine, a relaxation function often used in engineering applications. This subroutine is a 
two-dimensional function used to obtain the values of a variable at coordinates on a sur¬ 
face; for example, temperatures distributed across a metal plate. 

The second part (Figure 1-2) shows the VAX machine code generated by the FORTRAN 
compiler. Several compiler optimizations are indicated by the circled numbers next to the 
generated code lines. These are described in the notes that follow the figure. 
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SUBROUTINE RELAX2(EPS) 


PARAMETER 
DIMENSION 
COMMON X 


( M = 4 0 t N = 8 0 ) 
X ( 0 : M > 0 : N ) 



LOGICAL DONE 


1 DONE = ♦TRUE♦ 


10 


DO 10 J=1>N-1 
DO 10 1 = 1 > M- 1 

XNEN = (X(I- 1 »J)+ X(I +1 »J)+ X(I # J-1)+ X(I ♦ J +1 ) ) /4 
IF (ABS(XNEW-X(I »J) ) t GT♦ EPS) DONE = ♦FALSE♦ 
X(I>J) = XNEN 


IF (♦NOT♦ DONE) GO TO 1 


RETURN 

END 


Figure 1-1: RELAX Source Program 
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Figure 1-2: RELAX Machine Code (Optimized) 

Notes 

O All local variables are eliminated, so no $LOCAL PSECT is needed (and no base 
register is needed to point to it). 
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© Loop tops are aligned on longword boundaries using NOP instructions. 

© Register assignment for DONE; short form of constant. 

© Register assignment for J. 

© Register assignment for I. 

© Common subexpression (J*41) is hoisted from loop and assigned to a register. 

G Base address (X(l,l)) is loaded into a register. Six references to it. 

© Autoincrement address mode for X(I 1,J). 

© Register 6 is used for all temporary variables for line 7. 

® Peephole optimization; a divide by 4.0 is replaced by a multiply by 0.25. 

® XNEW loaded into Register 6, allowing for two-operand multiply. 

® In-line ABS function. 

© Flow boolean optimization for IF statement. 

© DO loop control using a single AOBLEQ (add one and branch less than or equal) 
instruction. 

© Logical test and branch in a single instruction. 

© Only 82 code bytes total (25 less than VAX FORTRAN V3). 
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Chapter 2 

VAX FORTRAN Implementation Notes 


This chapter discusses aspects of the relationship between the VAX FORTRAN language 
and its implementation on the VAX system. The purpose is to provide insights that will 
allow you to use VAX FORTRAN in a way that makes the best use of its features. The 
following subjects are discussed: 

• Program sections 

• Storage allocation 

• DO loops 

• ENTRY statement arguments 

• Floating-point data representation 

VAX FORTRAN calling conventions are treated separately in Chapter 3. 

2.1 Program Section Usage 

The storage required by a FORTRAN program unit is allocated in contiguous areas called 
program sections (PSECTs). The FORTRAN compiler implicitly declares three PSECTs: 

$CODE — Contains all executable code. 

$PDATA — Contains read-only data (for example, constants). 

$LOCAL — Contains read/write data that is local to the program unit. 

In addition, each common block you declare causes allocation of a PSECT with the same 
name as the common block. (The unnamed common block PSECT is named $BLANK.) 
Memory allocation and sharing are controlled by the linker according to the attributes of 
each PSECT; PSECT names and attributes are listed in Table 2-1. 

Each module in your program is named according to the name specified in the PROGRAM, 
BLOCK DATA, FUNCTION, or SUBROUTINE statement used in creating the module. 

The defaults applied to PROGRAM and BLOCK DATA statements are source-file- 
name$MAIN and source-file-name$DATA, respectively. 
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Table 2-1: PSECT Names and Attributes 


PSECT 

Name Use Attributes 


$CODE 


$PDATA 


$LOCAL 

$BLANK 


name(s) 


Executable code PIC,CON,REL,LCL,SHR,EXE,RD,NOWRT,LONG 

Read-only data: liter¬ 
als, read-only FOR¬ 
MAT statements PIC,CON,REL,LCL,SHR,NOEXE,RD,NOWRT,LONG 


Read/write data local 
to the program unit: 
user local variables, 
compiler temporary 
variables, argument 
lists, and descriptors 

Blank common block 


PIC, CON, REL,LCL,NOSHR,NOEXE,RD,WRT, LONG 
PIC,OVR,REL,GBL,SHR,NOEXE,RD,WRT,LONG 


Named common 

block(s) PIC,OVR,REL,GBL,SHR,NOEXE,RD,WRT,LONG 


Table 2-2 describes the meanings of the PSECT attributes. 


Table 2-2: PSECT Attributes 


Attribute 

Meaning 

PIC/NOPIC 

Position-independent or position-dependent 

CON/OVR 

Concatenated or overlaid 

REL/ABS 

Relocatable or absolute 

GBL/LCL 

Global or local scope 

SHR/NOSHR 

Shareable or nonshareable 

EXE/NOEXE 

Executable or nonexecutable 

RD/NORD 

Readable or nonreadable 

WRT/NOWRT 

Writable or nonwritable 

LONG/QUAD 

Longword or quadword alignment 


When the VAX Linker constructs an executable image, it divides the executable image 
into sections. Each image section contains PSECTs that have the same attributes. By 
arranging image sections according to PSECT attributes, the linker is able to control 
memory allocation. The linker allows you to allocate memory to your own specification by 
means of commands you include in an options file that is input to the linker. The options 
file is described in the VAX/VMS Linker Reference Manual. 
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2.2 Storage Allocation and Fixed-Point Data Types 

The default storage unit for VAX FORTRAN is the longword (four bytes). A storage unit is 
the amount of memory needed to store a REAL*4, LOGICAL*4, or INTEGER*4 value. 
REAL*8 and COMPLEX*8 values are stored in two successive storage units; REAL* 16 
and COMPLEX* 16 are stored in four successive units. These relative sizes must be taken 
into account when you associate two or more variables through an EQUIVALENCE or 
COMMON statement or by argument association. 

You can, however, declare integer and logical variables as 2-byte values to save space, to 
receive system service output values, or to be compatible with PDP-11 FORTRAN. Either 
specify the /NOI4 qualifier in the FORTRAN command line or explicitly declare a variable 
as INTEGER* 2 or LOGICAL* 2. This allows you to take advantage of the VAX processor’s 
ability to manipulate both 16- and 32-bit data efficiently. 

2.2.1 Integer Data Types 

FORTRAN supports INTEGER*2 and INTEGER*4 data types, which occupy two and four 
bytes of storage, respectively. The types can be mixed in computations; such mixed-type 
computations are carried out to 32 bits of significance and produce INTEGER*4 results. 

If you do not override the default storage allocation with the /NOI4 qualifier, four bytes are 
allocated for integer values. 

2.2.1.1 Relationship of INTEGER*2 and INTEGER*4 Values - INTEGER*2 values are stored as 
signed binary numbers in twos complement and they occupy two bytes of storage. INTE- 
GER*4 values are also stored as signed binary numbers in twos complement, but they 
occupy four bytes of storage. The lower addressed word of an INTEGER*4 value contains 
the low-order part of the value. 

INTEGER*2 values are a subset of INTEGER*4 values. That is, an INTEGER*4 value in 
the range -32768 to 32767 can be treated as an INTEGER*2 value. Conversion from 
INTEGER*4 to INTEGER*2 (without checks for overflow) consists of simply ignoring the 
high-order 16 bits of the INTEGER*4 value. This type of conversion provides an important 
FORTRAN usage, as illustrated in the following example. Given: 

CALL SUB(2) 

should the argument (2) be treated as an INTEGER*2 value or as INTEGER*4? By provid¬ 
ing an INTEGER*4 constant as the actual argument, SUB executes correctly even if its 
dummy argument is typed as INTEGER*2. 

2.2.1.2 Integer Constant Typing - Integer constants are generally typed according to the 
magnitude of the constant. In most contexts, INTEGER*2 and INTEGER*4 variables and 
integer constants can be freely mixed. You are responsible, however, for preventing inte¬ 
ger overflow conditions like those in the following example: 
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INTEGER*2 I 
INTEGER*^ J 
I = 32767 
J = I + 3 

In this example, I and 3 are INTEGER*2 values, and an INTEGER*2 result is computed. 
The 16-bit addition, however, will overflow the valid INTEGER*2 range and be treated as 
-32766. This value is converted to INTEGER*4 type and assigned to J. The overflow will 
be detected and reported if the default /CHECK = OVERFLOW qualifier is specified when 
the program unit is compiled. 

Contrast the preceding example with the following apparently equivalent program, which 
produces different results: 

INTEGER*2 I 
INTEGER*4 J 
PARAMETER (1=32767) 

J = I + 3 

In this case, the compiler performs the addition of the constant 3 and the parameter con¬ 
stant 32767, producing a constant result of 32770. The compiler recognizes this as an 
INTEGER*4 value. Thus, J is assigned the value 32770. 

2.2.1.3 Integer-Valued Intrinsic Functions - A number of the intrinsic functions provided by 
VAX FORTRAN (see Chapter 10 of Programming in VAX FORTRAN) produce integer 
results from real arguments (for example, INT). In order to support such functions in a 
manner compatible with both INTEGER*2 and INTEGER*4 modes, two versions of these 
integer-valued intrinsic functions are supplied. The compiler chooses the version that 
matches the compiler /I4 qualifier setting (/I4 or /NOI4). This process is similar to generic 
function selection (described in Chapter 10 of Programming in VAX FORTRAN) except 
that the selection is based on the mode of the compiler, rather than on the argument data 
type. 

In some cases, you may need to use the version of an integer-valued intrinsic function that 
is the opposite of the compiler qualifier setting. For this reason, a pair of additional intrin¬ 
sic function names are provided for each standard integer-valued intrinsic function. The 
names of the INTEGER*2 versions are prefixed with I, and the names of the INTEGER*4 
versions with J (for example, IIABS and JIABS). See Appendix D of Programming in VAX 
FORTRAN for a complete list of intrinsic functions. 

2.2.2 BYTE (L0GICAL*1) Data Type 

VAX FORTRAN’S BYTE data type lets you take advantage of the byte-processing capabili¬ 
ties of the VAX processor. BYTE, or LOGICAL* 1, is a signed integer data type and is use¬ 
ful for storing and manipulating Hollerith data. 
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In general, when different data types are used in a binary operation, the lower-ranked type 
is converted to the higher-ranked type prior to computation. (Data type rank is discussed 
in the Programming in VAX FORTRAN.) However, in the case of a byte variable and an 
integer constant in the range representable as a byte variable (-128 to 127), the integer 
constant is treated as a byte constant; and the result is also of byte data type. 

2.2.3 Zero-Extend Intrinsic Functions for Converting Data Types 

VAX FORTRAN normally converts a smaller fixed-point data type to a larger fixed-point 
data type by sign-extending the smaller value. This means that the high-order bits of the 
larger data type are set to the same value as the sign bit of the smaller data type. Thus, if 
you are converting a BYTE value to an INTEGER*4 value, the bits of the three high-order 
bytes of the INTEGER*4 value are set to the same value as the sign bit of the BYTE value. 
Generic and specific conversion functions are provided with VAX FORTRAN: 

• The generic function ZEXT allows you to zero-extend, instead of sign-extend, a value 
to either INTEGER*2 or INTEGER*4, depending on the setting of the /I4 qualifier in 
the FORTRAN command line. This means that the high-order bits of the larger data 
type are set to zero, rather than to the sign bit of the smaller data type. 

• The specific functions IZEXT and JZEXT zero-extend a value to either INTEGER*2 
or INTEGER*4, respectively. The argument to IZEXT can be any fixed-point data 
type that occupies one or two bytes of storage, and the argument to JZEXT can be any 
fixed-point data type that occupies one, two, or four bytes of storage. 

You use the zero-extend functions primarily for bit-oriented operations. The following is 
an example of the use of the ZEXT function: 

INTEGER*2 W_UAR / 7 FFFF ')</ 

INTEGER*^ L _ 0 A R 
L _ 0 A R = ZEXT(W _ U A R) 

This example stores an INTEGER*2 quantity in the low-order 16 bits of an INTEGER*4 
quantity, with the resulting value of L_VAR being 'OOOOFFFF'X. If the ZEXT function 
had not been used, the resulting value of this example would have been 'FFFFFFFF'X 
because W_VAR would have been converted to the left-hand operand’s data type by sign 
extension. 

When you are using the zero-extend intrinsic functions, it is important to remember that 
integer constants in the range of-32768 to 32767 are INTEGER*2. Therefore, JZEXT(-l) 
is equal to 65535. The storage requirements for integer constants are never less than two 
bytes. Integer constants within the range of constants that can be represented by a single 
byte still require two bytes of storage. 

2.3 Iteration Count Model for DO Loops 

The FORTRAN DO statement has the following features: 

• The control variable can be an integer or real variable. 
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• The initial value, step size, and final value of the control variable can be any expres¬ 
sion that produces a result with an integer or real data type. 

• The number of times the loop is executed (the iteration count) is determined at the 
initialization of the DO statement; it is not reevaluated during successive executions 
of the loop. Thus, the number of times the loop is executed is not affected by changes to 
the values of the parameter variables used in the DO statement. 

2.3.1 Cautions Concerning Program Transportability 

Some common practices associated with the use of DO statements may not have the 

intended effects when used with VAX FORTRAN. For example, in VAX FORTRAN: 

• Assigning a value to the control variable within the body of the loop that is greater 
than the final value does not always cause early termination of the loop. 

• Modifying a step-size variable or a final value variable within the body of the loop 
does not modify the loop behavior or terminate the loop. 

• Using a negative step size (for example, DO 10 I = 1,10,-1) in order to set up an arbi¬ 
trarily long loop that is terminated by a conditional control transfer within the loop 
results in zero iterations of the loop body if /F77 is in effect. A zero step size may result 
in an error (refer to the iteration count computation in Section 2.3.2). 

2.3.2 Iteration Count Computation 

Given the following sample DO statement: 

DO label* 0 = m1 *m2 t m3 

(where ml, m2, and m3 are any expressions), the iteration count is computed as follows: 

count = N A X(0 * IN T( (m2-m1+ m3)/m3) ) 

This computation: 

• Makes possible an iteration count of zero (in which case the body of the loop is not 
executed). 

• Permits the step size (m3) to be negative or positive, but not zero. 

• Gives a well-defined and predictable count value for expressions resulting from any 
combination of the allowed result types. (Note, however, that the effects of round-off 
error inherent in any floating-point computation may cause the count to be greater or 
less than desired when real values are used.) 

• Differs from the usual FORTRAN-66 implementations: the minimum count value in 
that version was one and the current minimum value is zero (refer to Section A.l for 
compatibility information). Thus, when the /F77 qualifier (the default) is used, the 
minimum count is zero, and when /NOF77 is used, the minimum count is one. 
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Under certain conditions it is not necessary to compute the iteration count explicitly. For 
example, if all of the parameters are of type integer and if the parameter values are not 
modified in the loop, then the FORTRAN-generated code controls the number of iterations 
of the loop by comparing the control variable directly with the final value. 

2.4 ENTRY Statement Arguments 

The association of actual and dummy arguments is described in Programming in VAX 
FORTRAN . In general, that description suffices for most cases. However, the VAX FOR¬ 
TRAN implementation of argument association in ENTRY statements differs from that of 
some other implementations of FORTRAN. 

As described in Chapter 3, VAX FORTRAN uses the reference and descriptor mechanisms 
to pass arguments to called procedures (for numeric and character arguments, respec¬ 
tively). Some other implementations of FORTRAN use the copy-in/copy-out method. This 
distinction becomes crucial when reference is made to dummy arguments in ENTRY 
statements. 

While standard FORTRAN allows you to use the same dummy arguments in different 
ENTRY statements, it permits you to refer only to those dummy arguments that are 
defined for the ENTRY point being called. For example: 

SUBROUTINE SUB1(X»Y#Z) 


ENTRY ENT 1(X»A> 


ENTRY ENTZ(B fZ »Y) 

Given this, you can make the following references: 

CALL Valid References 

SUB 1 X Y Z 

ENT 1 X A 

ENTZ B Z Y 

FORTRAN implementations that use the copy-in/copy-out method, however, permit you to 
refer to dummy arguments that are not defined in the ENTRY statement being called. For 
example: 

SUBROUTINE INIT(A»B»C) 

RETURN 

ENTRY CALC(Y »X) 

Y = ( A * X + B ) / C 

END 
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You can use this nonstandard method in copy-in/copy-out implementations because a sep¬ 
arate internal variable is allocated for each dummy argument in the called procedure. 
When the procedure is called, each scalar actual argument value is assigned to the corre¬ 
sponding internal variable. These variables are then used whenever there is a reference to 
a dummy argument within the procedure. On return from the called procedure, modified 
dummy arguments are copied back to the corresponding actual argument variables. 

When an entry point is referenced, all of its dummy arguments are defined with the values 
of the corresponding actual arguments, and they may be referenced on subsequent calls to 
the subprogram. However, it is not advisable to attempt this in programs that are to be 
executed on VAX FORTRAN, or on other systems that use the call-by-reference (or 
descriptor) method. 

VAX FORTRAN creates associations between dummy and actual arguments by passing 
the address of each actual argument, or descriptor, to the called procedure. Each reference 
to a dummy argument generates an indirect address reference through the actual argu¬ 
ment address. When control returns from the called procedure, the association between 
actual and dummy arguments ends. The dummy arguments do not retain their values and 
therefore cannot be referenced on subsequent calls. Thus, to perform the sort of nonstan¬ 
dard references shown in the previous example, the subprogram must copy the values of 
the dummy arguments. For example: 

SUBROUTINE I N I T < A 1 »B 1 »C 1 > 

SAME A * B tC 
A = A1 
B = B1 
C = Cl 
RETURN 

ENTRY CALC(Y tX) 

Y = <A*X+B)/C 

END 

Note that the use of the FORTRAN SAVE statement in this example ensures that the val¬ 
ues of A, B, and C will be retained from one call to the next. 

2.5 Floating-Point Data 

A floating-point value is represented by from 4 to 16 contiguous bytes, depending upon the 
specific data type. The number of exponent and fraction bits also depends upon the specific 
data type. The bits are numbered from right to left, 0 through n. Bit 15 is the sign bit. The 
general format of floating-point data is as follows (broken lines indicate where boundaries 
change, depending upon the specific data type): 
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15 


0 


EXPONENT 


FRACTION 


: A 


FRACTION 


,31 


FRACTION 


16 , 


_l 


Individual floating-point data types are illustrated and explained in Appendix C of Pro¬ 
gramming in VAX FORTRAN. Data characteristics are described in the following section. 

2.5.1 VAX FORTRAN Programming Restrictions 

Certain FORTRAN programming practices that are commonly used, though not permit¬ 
ted under the rules for standard FORTRAN, may not produce the expected results with 
VAX FORTRAN. These are described in the following sections. 

2.5.1.1 Reserved Operand Faults - Accessing a floating-point variable that contains an 
invalid floating-point value (-0.0), indicated by an exponent field of 0 and a sign bit of 1, 
causes a reserved operand fault in the VAX hardware. An error is reported and, by default, 
your program terminates. 

There are four ways to create reserved operand values: 

• The VAX hardware stores a reserved operand value as the result of the floating-point 
arithmetic traps, floating overflow, and floating zero divide. 

• The mathematical function library returns a reserved operand value if the function is 
called incorrectly or if the argument is invalid. For example: 

SORT(- 1♦0) 

This return value can be modified with a condition handler (see Chapter 6). 
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• Integer arithmetic and logical operations can create reserved operand bit patterns in 
floating-point variables and arrays associated with integers. Associations of this kind 
can occur through EQUIVALENCE, COMMON, or argument association. For 
example: 

EQUIVALENCE (X *1) 

I = 32768 
X = X + 1 ♦ 0 

Adding 1.0 to X causes a reserved operand fault because the integer value 32768 is a 
reserved operand when interpreted as a floating-point value. 

• Octal and hexadecimal constants can be used to create reserved operand values. 

The first two cases occur when invalid programs or data are used. The last two cases can 
occur inadvertently in a program and may not be detected by other implementations of 
FORTRAN. 

2.5.1.2 Representation of 0.0 - The VAX hardware defines 0.0 as any bit pattern that has 
an exponent field of 0 and a sign bit of 0, regardless of the value of the fraction. When a bit 
pattern that is defined as 0.0 is used in a floating-point operation, the VAX hardware sets 
the fraction field to 0. One possible effect is that nonzero integers equivalenced to floating¬ 
point values may be interpreted as zero. 

Logical operations can have a similar effect, as shown in the following example: 

REAL*4 X 

EQUIVALENCE (X »I ) 

I = 64 

IF (X ♦ EQ ♦ 0) GO TO 10 

The branch will always be taken because the bit pattern that represents the integer value 
is equivalent to zero when interpreted as a floating-point value. 

2.5.1.3 Sign Bit Tests - The bit used as the sign bit of a floating-point value is not the same 
bit as the sign bit of an equivalenced INTEGER*4 value. Consequently, you must test the 
sign of a value by testing the correct data type. For example: 

EQUIVALENCE (X tl ) 

I = 40000 

IF (X ♦ GT ♦ 0) GO TO 10 

The branch is not taken because the bit pattern that represents the integer value 40000 is 
negative (bit 15 is set) when interpreted as a floating-point value. 

2.5.2 Effect of the /G.FL0ATING Qualifier 

The /G_FLOATING compiler qualifier causes double-precision quantities to have the 
G_floating type. If this qualifier is not used, the D_floating type is assumed. 
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Program units that exchange double-precision values should use either G_floating or 
D_floating data types, but not both. Because their formats are different, mixing the two 
types can produce unpredictable results. Under certain circumstances, however, you may 
wish to convert one data type to the other (refer to Section 2.5.3). Passing a REAL*4 varia¬ 
ble as an actual argument to a routine in which the corresponding dummy argument is of 
the G_floating data type can also give incorrect results. 

2.5.3 Conversion Between D.floating and G_floating Data Types 

Although you should not normally mix the D_floating and the G_floating implementa¬ 
tions of REAL*8, there may be times when you must convert one to the other so that the 
values are compatible within the same program. For example, you may have a program 
that uses G_floating values for its double-precision work but which must access an 
unformatted file of D_floating values. The Run-Time Library provides procedures that 
perform conversions between the D_floating and the G_floating data types. 

It is possible for your program to manipulate RE AL*8 variables whose representations are 
the opposite of that specified by the /G-FLOATING command qualifier. You must not per¬ 
form floating-point arithmetic on such values. However, these variables can appear in 
unformatted I/O statements, in assignment statements, and as actual arguments. 

You should be aware of the following properties of the Run-Time Library data type conver¬ 
sion procedures: 

• Conversion from D_floating to G_floating may involve rounding of the values. 

• Conversion from G_floating to D_floating is exact; there is no rounding of the values. 
However, if the G_floating value is not representable as a D_floating value, one of the 
following occurs: 

— If the value is too large, the procedure signals an overflow (and produces a floating 
reserved operand). 

— If the value is too small, the procedure produces a value of 0.0. If the calling proce¬ 
dure enabled floating underflow, the procedure signals floating underflow. 

• If you attempt to convert a floating reserved operand, the procedure signals a reserved 
operand fault. 

The Run-Time Library provides two conversion functions and two conversion subroutines. 

2.5.3.1 Run-Time Library Conversion Functions - One function converts D_floating values to 
G_floating values and the other performs the opposite conversion. These functions have 
the forms: 

MTH$CVT_D_G(D_value) 

MTH$CVT_G_D(G_value) 
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where: 

D_value 

is a REAL*8 (D_floating) value to be converted to the corresponding G_floating 
representation. 

G_value 

is a REAL*8 (G_floating) value to be converted to the corresponding D_floating 
representation. 

You must declare these function names as REAL*8 to prevent them from being implicitly 
typed as integer. 

2.5.3.2 Run-Time Library Conversion Subroutines - One subroutine converts arrays of 
D_floating values to G_floating values, and the other performs the opposite conversion. 
These subroutines have the forms: 

CALL MTH$CVT_DA_GA(D_source, G_dest, count) 

CALL MTH$CVT_GA_DA(G_source, D_dest, count) 

where: 

D_source 

is an array of REAL*8 (D_floating) values to be converted to the G_floating type. 
G_source 

is an array of REAL*8 (G_floating) values to be converted to the D_floating type. 
G_dest,D_dest 

are the REAL*8 arrays in which the converted values are to be stored. 

count 

is an INTEGER*4 value that is the number of array elements to be converted. 

You can perform an in-place conversion by specifying the same array as the source and the 
destination argument. However, you must not specify a partial overlap between the source 
and destination arrays. The following calls on the conversion subroutines are valid: 

CALL MTH$CUT_DA_GA(X»Y#100) 

CALL MTH$COT_GA_DA(X(B) »X<G) * 95) 

2.5.3.3 Sample Conversions - The following FORTRAN program reads 100 D_floating 
values from an unformatted file, converts them to G_floating values, calculates a root- 
mean-square in G_floating, and writes the result to another unformatted file as a 
D_floating value. 
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OPTIONS /G_FLOATING 


REAL*8 X(100) » ROOT # SUN 
REAL*8 MTH$COT_G_D 

READ(1) X 

CALL MTH$C0T_DA_GA(X # X #100) 

SUM =0*0 
DO 1=1>100 

SUM = SUM + X(I)**2 
END DO 

ROOT = SORT(SUM/100) 

WRITE (2) MTH$COT_G_D(ROOT) 

TYPE * * 'The root-wean-square is'# ROOT 
END 
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Chapter 3 

FORTRAN Call Conventions 


VAX FORTRAN provides you with a variety of mechanisms for gaining access to proce¬ 
dures and system services external to your FORTRAN programs. By including CALL 
statements or function references in your source program, you can use procedures such as 
mathematical functions, VAX/VMS system services, and routines written in languages 
other than FORTRAN. 

This chapter provides information on the VAX procedure-calling standard and describes 
how to access VAX system services. Detailed information about calling and using the RMS 
(Record Management Services) system service is provided in Chapter 4. 

3.1 VAX Procedure-Calling Standard 

Programs compiled by the VAX FORTRAN compiler conform to the standard defined for 
VAX procedure calls (see Appendix C of the VAX/VMS Run-Time Library Reference Man¬ 
ual). This standard prescribes how arguments are passed, how function values are 
returned, and how procedures receive and return control. 

If you want to write routines that can be called from FORTRAN programs, you should pay 
particular attention to the argument list descriptions and to the object code format descrip¬ 
tion in Section 3.4. 

3.1.1 Argument Lists 

The VAX procedure-calling standard defines an argument list as a sequence of longword 
(4-byte) entries, the first of which contains an argument count. The argument count is con¬ 
tained in the first byte in the first entry in the list. It indicates how many arguments follow 
in the list. 

Memory for FORTRAN argument lists and for VAX descriptors (generated from the use of 
%DESCR or by passing CHARACTER data) is usually allocated statically. To optimize 
space and time, the argument lists are pooled, and argument list entries are initialized at 
compile time, when possible. Sometimes several calls can use the same argument list. For 
example: 
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X = DIZ(Y) 

Z = DIZ(Y) * DIZ(Z) 

A = X + Z + DIZ(Y) 

All of the references to DIZ(Y) use the same argument list. 

Omitted arguments (for example, CALL X(A„B)) are represented by an argument list 
entry that has a value of zero. 

See Section 3.4.1 for examples of object code generated for FORTRAN argument lists. 


3.1.2 Argument-Passing Mechanisms 

The VAX procedure-calling standard defines three mechanisms by which arguments are 
passed to procedures: 

• Argument passing by immediate value — The argument list entry is the value. 

• Argument passing by reference — The argument list entry is the address of the value. 

• Argument passing by descriptor — The argument list entry is the address of a 
descriptor of the value. 

By default, VAX FORTRAN uses the reference and descriptor mechanisms to pass argu¬ 
ments, depending on the argument’s data type. The reference mechanism is used to pass 
all numeric actual arguments: logical, integer, real, and complex. The descriptor mecha¬ 
nism is used to pass all character actual arguments. 

3.1.3 Built-In Functions for Passing Arguments to Non-FORTRAN Procedures 

In some cases, a function reference or call to a non-FORTRAN procedure requires argu¬ 
ments in a form other than that provided by the reference and descriptor mechanisms, the 
VAX FORTRAN default mechanisms. Calls to VAX/VMS system services are such a case. 
VAX FORTRAN provides three built-in functions for passing arguments when you cannot 
use the default mechanisms. These built-in functions are: 

• Argument list built-in functions (%VAL, %REF, %DESCR) 

• %LOC built-in function 

Except for the %LOC built-in function, which can be used in any arithmetic expression, 
these functions can appear only as unparenthesized arguments in actual argument lists. 
Note that the argument list built-in functions and %LOC built-in function are rarely used 
to call a procedure written in FORTRAN. The use of these functions in system service calls 
is described in Section 3.3.4. The sections that follow describe their use in general. 

3.1.3.1 %VAL Function - The %VAL function passes the argument list entry as a 32-bit 
immediate value. It has the form: 

%VAL(arg) 
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The argument list entry (arg) is the value of the entry. Because argument list entries are 
longwords, the argument value must be an INTEGER, LOGICAL, or REAL*4 constant, 
variable, array element, or expression. If the value is a byte or word, it is sign extended to a 
longword. The ZEXT intrinsic function can be used to produce a zero-extended value, 
rather than a sign-extended value. You may need to use the %VAL function when passing 
an address argument to a FORTRAN subprogram. Address arguments can occur in fields 
used to interface to routines written in other languages. Using the %VAL function to pass 
an address argument pointing to a data item is equivalent to passing the item itself by 
reference. 

3.1.3.2 %REF Function - The %REF function passes the argument list entry by reference. 
It has the form: 

%REF(arg) 

The argument list entry (arg) is the address of the value. The argument value can be a 
numeric or character expression, array, array element, or procedure name. This is the 
default FORTRAN method for passing all numeric values. 

3.1.3.3 %DESCR Function - The %DESCR function passes the argument list entry by 
descriptor. It has the form: 

%DESCR(arg) 

The argument list entry (arg) is the address of a descriptor of the value. The argument 
value can be any type of FORTRAN expression. The compiler can generate VAX 
descriptors for all FORTRAN data types. 

The descriptor mechanism is the default FORTRAN mechanism for passing character 
arguments because the subprogram may need to know the length of the character argu¬ 
ment. In particular, FORTRAN always generates code to refer to character dummy argu¬ 
ments through the addresses in their descriptors. 

3.1.3.4 Examples Of %VAL, %REF, %DESCR - The following examples illustrate the use of 
the argument list built-in functions. 

CALL SUB(2 tZV AL(2)) 

The first constant is passed by reference. The second constant is passed by immediate 
value. 

CHARACTER*10 A »B 
CALL SUB ( A *7.REF ( B ) ) 

The first character variable is passed by descriptor. The second character variable is 
passed by reference. 

INTEGER I A R Y(2 0) t JARY(20) 

CALL SUB <I ARY >XDESCR(JARY) ) 

The first array is passed by reference. The second array is passed by descriptor. 

See Section 3.4.2 for examples that include the generated object code. 
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3.1.3.5 %LOC Built-In Function - The %LOC built-in function computes the address of a 
storage element as an INTEGER*4 value. This value can be used in an arithmetic expres¬ 
sion. It is particularly useful for certain system services or non-FORTRAN procedures 
that may require argument data structures containing the addresses of storage elements. 
The data structures should be declared volatile (see VOLATILE statement in Program¬ 
ming in VAX FORTRAN to protect them from possible optimizations. The effects of vola¬ 
tile declarations and the situations in which they should be used are discussed at length in 
Section 1.3.2.2. 

3.1.4 Function Return Values 

The method that function procedures use to return values depends on the data type of the 
value, as summarized in Table 3-1. 


Table 3-1: Function Return Values 


Data Type Return Method 


Logical 

Integer 

REAL*4 

REAL*8 

COMPLEX*8 

REAL* 16 
COMPLEX* 16 


General register RO 


RO: High-order result 
Rl: Low-order result 

RO: Real part 
Rl: Imaginary part 

An extra entry is added as the first entry of the argument list. This new first- 
argument entry points to the result. 


Character An extra entry is added as the first entry of the argument list. This new first- 

argument entry points to a character string descriptor. At run time, storage 
is allocated to contain the value of the result, and the proper address is stored 
in the descriptor. 


3.2 Calling External Procedures 

A procedure is a subprogram that performs one or more computations for other programs. 
Procedures can be either functions or subroutines. Both functions and subroutines can 
return values by storing them in variables specified in the argument list or in common 
blocks. A function, unlike a subroutine, can also return a value to the calling program by 
assigning the value to the function's name. See Programming in VAX FORTRAN for 
information on defining and invoking subprograms. 
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3.3 Calling VAX/VMS System Services 

You can invoke system services in a FORTRAN program with a function reference or a 
subroutine CALL statement that specifies the system service you want to use. To specify a 
system service, use the form: 

S Y S$service-name(arg,... ,arg) 

You pass arguments to the system services according to the requirements of the particular 
service you are calling; an immediate value, an address, the address of a descriptor, or the 
address of a data structure may be needed. Section 3.3.4 describes the FORTRAN syntax 
rules for each of these cases. See the VAX/VMS System Services Reference Manual for a full 
definition of individual services. 

Methods for calling the system services provided by the VAX/VMS operating system are 
discussed in the sections that follow. 

3.3.1 Obtaining Values for System Symbols 

VAX/VMS uses symbolic names to identify return status values, condition values, and 
function codes for system services: 

• Return status values are used for testing the success of system service calls. 

• Condition values are used for error recovery procedures (see Chapter 6). 

• Function codes are the symbolic values used as input arguments to system service 
calls. 

The values chosen determine the specific action desired of the service. 

The VAX/VMS System Services Reference Manual describes the symbols that are used 
with each system service. The VAX/VMS I/O User’s Reference Manual describes the sym¬ 
bols that are used with I/O-related services. 

The FORTRAN symbolic definition library FORSYSDEF contains FORTRAN source defi¬ 
nitions for related groups of system symbols. Each related group of system symbols is 
stored in a separate text module; for example, the module $IODEF in FORSYSDEF con¬ 
tains PARAMETER statements that define the I/O function codes. The modules in FOR¬ 
SYSDEF correspond to the symbolic definition macros that VAX/VMS MACRO 
programmers use to define system symbols. The modules have the same names as the 
macros and contain FORTRAN source code, which is functionally equivalent to the 
MACRO source code. 

In addition, the module $SYSSRVNAM in FORSYSDEF contains declarations for all sys¬ 
tem-service names. It contains the necessary INTEGER and EXTERNAL declarations for 
the system-service names. (The module also contains comments describing the arguments 
for each of the system services.) 
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The modules in FORSYSDEF contain definitions for constants, bit masks, and data struc¬ 
tures. See Section 3.3.4.4 for a description of how to create data arguments in FORTRAN. 
Refer to Appendix C for a list of modules that are in FORSYSDEF. Note that module 
$SSDEF contains system-service return status codes and is generally required for all 
services. 

You can access the modules in the FORSYSDEF library with the INCLUDE statement, 
using the following format: 

INCLUDE ’(module-name)’ 

where: 

module-name 

is the name of a module contained in FORSYSDEF. The library FORSYSDEF is 
searched if the specified module was not found in a previously searched library. 

3.3.2 Calling System Services by Function Reference 

In most cases, after calling a system service you should check the return status. Therefore, 
you should call system services by function reference rather than by issuing a call to a 
subroutine. 

For example: 

INCLUDE 7 ($SSDEF) 7 
INCLUDE 7 <*SYSSRONAM) 7 
INTEGER*2 CHANNEL 



MBX-STATUS = SYS$CREMBX( ^CHANNEL t > t t * 'MAILBOX 7 ) 

IF (MBX.STATUS ♦NE♦ SS$_NORMAL) GO TO 100 

In this example, the system service referenced is the Create Mailbox system service. An 
INTEGER*2 variable (CHANNEL) is declared to receive the channel number. 

The function reference allows a return status value to be stored in the variable 
MBX_STATUS, which can then be checked for correct completion on return. If the func¬ 
tion’s return status is not SS$_NORMAL, failure is indicated and control is transferred to 
statement 100. At that point, some form of error processing can be undertaken. 

You can also test the return status of a system service as a logical value. The status codes 
are defined so that when they are tested as logical values, successful codes have the value 
true and error codes have the value false. Thus, the fourth line in the example above could 
be changed to the following: 

IF (♦ NOT♦ MBX-STATUS) GO TO 100 


Refer to the VAX/VMS System Services Reference Manual for information concerning 
return status codes. The return status codes are included in the description of each system 
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3.3.3 Calling System Services as Subroutines 

Subroutine calls to system services are made in the same way that calls are made to any 
other subroutine. For example, to call the Create Mailbox system service, issue a call to 
SYS$CREMBX, passing to it the appropriate arguments, as follows: 

CALL SYS$CREMBX( > CHANNEL , , » » , 7 MAILBOX 7 ) 

This call corresponds to the function reference described in Section 3.3.2. The main differ¬ 
ence is that the status code returned by the system service is not tested. For this reason, 
you should avoid this method of calling system services whenever it is anticipated that the 
service could fail for any reason. 

3.3.4 Passing Arguments to System Services 

The description of each system service in the VAX/VMS System Services Reference Manual 
specifies the argument-passing method for each argument. There are four common 
methods: 

• By immediate value 

• By address (this is the FORTRAN default termed “by reference”) 

• By descriptor (this is the FORTRAN default for CHARACTER arguments) 

• By data structure 

These methods are discussed separately in Sections 3.3.4.1 through 3.3.4.4. 

You can determine the arguments required by a system service from the service descrip¬ 
tion in the VAX/VMS System Services Reference Manual. Each system service description 
indicates the service name, the number of arguments required, and the positional depen¬ 
dency of each argument. Many arguments to system services are optional. However, if you 
omit an optional argument, you must include a comma to indicate the absence of that 
argument. For example, the SYS$TRNLOG system service takes six arguments. If you 
omit the last three arguments, you must include commas to indicate their existence, as 
follows: 

ISTAT = SYS$TRNLOG( 7 L0GNAM 7 ^LENGTH>BUFFA , »») 

An invalid reference results if you specify: 

ISTAT = SYS$TRNLOG( 7 L0GNAM 7 ^LENGTHtBUFFA) 

This reference provides only three arguments, not the required six. 

When you omit an optional argument, the compiler supplies a default value of zero. 

3.3.4.1 Immediate Value Arguments - Use value arguments when the description of the 
system service specifies that the argument is a “number,” “mask,” “mode,” “value,” “code,” 
or “indicator.” You must use the FORTRAN argument list built-in function %VAL (see Sec¬ 
tion 3.1.3.1) whenever this method is required. 

Immediate value arguments are used for input arguments only. 
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3.3.4.2 Address Arguments - Use address arguments when the description of the system 
service specifies that the argument is “the address of.” (However, refer to Section 3.3.4.3 to 
determine what to do when “the address of a descriptor” is specified.) In FORTRAN, this 
argument-passing method is called “by reference.” Because this method is the default for 
FORTRAN numeric arguments, you need to specify the %REF argument list built-in func¬ 
tion only when the data type of the argument is not logical, integer, real, or complex. 

The argument description also gives the hardware data type required. 

For arguments described as “address of an entry mask” or “address of a routine,” declare 
the argument value as an external procedure. For example, if a system service requires the 
address of a routine and you want to specify the routine HANDLER3, specify: 

EXTERNAL HANDLER3 

in the declarations portion of the FORTRAN program. This specification defines the 
address of the routine for use as an input argument. 

Address arguments are used for both input and output. 

• For input arguments that refer to byte, word, or longword values, you can specify 
either constants or variables. If you specify a variable, you must declare it to be equal 
to or longer than the data type required. Table 3-2 lists the variable data type require¬ 
ments for both input and output arguments. 

• For output arguments you must declare a variable of exactly the length required to 
avoid including extraneous data. If, for example, the system returns a byte value in a 
word-length variable, the leftmost eight bits of the variable are not overwritten on 
output. The variable, therefore, does not contain the data you expect. 

To store output produced by system services, you must allocate sufficient space to con¬ 
tain the output. You make this allocation by declaring variables of the proper size. For 
an illustration, refer to the Translate Logical Name system service example in Sec¬ 
tion 3.3.4.3. This service returns the length of the equivalent name string as a 2-byte 
value. 

If the output is a quadword value, you must declare an array of the proper dimensions. 
For example, the Get Time system service (SYS$GETTIM) returns the time as a 
quadword binary value, and you would declare the following: 

INCLUDE 7 ($SYSSR0NAM) ' 

INTEGER*^ SYSTIM(2) 


ISTAT = SYS$GETTIM(SYSTIM) 

The type declaration INTEGER*4 SYSTIM(2) establishes a vector consisting of two 
longwords into which the time value is stored. 
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Table 3-2: Variable Data Type Requirements 


VAX/VMS 
Type Required 


Input Argument Declaration Output Argument Declaration 


Byte 

Word 

Longword 

Quadword 

Indicator 

Character string 
descriptor 

Entry mask or 
routine 


BYTE, INTEGER*2, INTEGERS 
INTEGERS, INTEGERS 
INTEGERS 

Properly dimensioned array 


BYTE 

INTEGERS 

INTEGER*4 

Properly dimensioned array 


LOGICAL 

CHARACTER^ 


CHARACTER^ 


EXTERNAL 


3.3.4.3 Descriptor Arguments - Descriptor arguments are used for input and output of 
character strings. Use a descriptor argument when the argument description specifies 
“address of a character string descriptor.” Because this method is the default for FOR¬ 
TRAN character arguments, you need to specify the %DESCR argument list built-in only 
when the data type of the argument is not character. 

On input, a character constant, variable, array element, or expression is passed to the sys¬ 
tem service by descriptor. On output, two arguments are needed: (1) the character variable 
or array element to hold the output string and (2) an INTEGER*2 variable that is set to the 
actual length of the output string. Thus, in the following example of the Translate Logical 
Name system service (SYS$TRNLOG), the logical name LOGNAM is translated to its 
associated name or file specification, and the output string and string length are stored in 
the variables EQV_BUFFER and W_NAMELEN, respectively: 

INCLUDE 7 ($ S Y S S R 0 N A M) 7 
INTEGER*2 W_NAMELEN 
INTEGER*^ TRN_STATUS 
CHARACTER*G3 EDO-BUFFER 


TRN-STATUS = SYS$TRNLOG( 'LOGNAM 7 * W-NAMELEN t EQU-BUFFER * * t) 

3.3.4.4 Data Structure Arguments - Data structure arguments are used when the argu¬ 
ment description specifies “address of a list,” “address of a control block,” or “address of a 
vector.” The data structures required for these arguments are constructed in VAX FOR¬ 
TRAN with structure declarations blocks and the RECORD statement. The storage 
declared by a RECORD statement is allocated in exactly the order given in the structure 
declaration, with no space between adjacent items. For example, the item list required for 
the SYS$GETJPI system service requires a sequence of items of two words and two 
longwords each. By declaring each item as part of a structure, you ensure that the fields 
and items are allocated contiguously: 
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STRUCTURE /GETJPI-STR/ 

INTEGER*2 BUFLEN # ITMCGD 
INTEGER*^ BUFADR # RETLEN 
END STRUCTURE 

RECORD /GET JPI_STR/ LIST(5) 

If a given field is provided as input to the system service, the calling program must fill the 
field before the system service is called. You can accomplish this with data initialization 
(for fields with values that are known at compile time) and with assignment statements 
(for fields that must be computed). 

When the data structure description requires a field that must be filled with an address 
value, use the %LOC built-in function to generate the desired address (see Section 3.1.3.5). 
When the description requires a field that must be filled with a symbolic value (system- 
service function code), you can define the value of the symbol by the method described in 
Section 3.3.1. 

3.3.4.5 Examples of Passing Arguments - Figure 3-1 shows a complete subroutine that uses 
a data structure argument to the SYS$GETJPI system service. 

C Subroutine to obtain absolute and incremental values of 
C process parameters: 

C CPU time# Buffered I/O count# Direct I/O count# PaSe faults. 

SUBROUTINE PROCESS-INFO(ABS_VALUES# INCR-UALUES) 

C Set up implicit data types so that data types indicate sizes 

IMPLICIT INTEGER*2(W) # INTEGER*4(L) 

C Define the symbolic values used in the GETJPI call 

INCLUDE 7 ($JPIDEF) 7 
INCLUDE 7 ($ S Y S S R U N A M) 7 

C Declare the arguments and working storage 

INTEGER*^ ABS-UALUES(4 )* INCR_UALUES(4) # LCL.UALUES(4) 

C Declare the SYS$GETJPI item list data structure in a structure declaration 

STRUCTURE /GETJPI_STR/ 

INTEGER*2 BUFLEN /4/» ITMCOD /O/ 

INTEGER*4 BUFADR# RETLEN /0/ 

END STRUCTURE 
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C Create a record with the fields defined in the structure declaration 

RECORD /GETJPI_STR/ LIST<5) 

C Assign all static values in the item list 

LI ST(1) ♦ITMCOD = JPI$_CPUTIM 
LIST(2)♦ITMCOD = JPI$_BUFIO 
LIST(3)♦ITMCOD = JPI$_DIRIO 
LIST(4)♦ITMCOD = JPI$_PAGEFLTS 

C AssiSn all item fields requiring addresses 

L I ST ( 1 ) 4 BUFADR = 7. L 0 C ( L C L _ U A L U E S ( 1 ) ) 

L I ST ( 2 ) 4 BUFADR = 7.L0C ( LCL_UALUES ( 2 ) ) 

LIST(3) * BUF ADR = 1LOC (LCL_UALUES(3) ) 

LIST (4) .BUFADR = 7.L0C < LCL_UALUES ( 4 ) ) 

C Perform the system service call 

CALL SYS$GETJPI( t * tLIST t t t) 

C Assign the new values to the arguments 

DO 1=1#4 

INCR-UALUES(I) = LCL-UALUES(I) - ABS_UALUES(I) 

ABS_UALUES(I) = LCL_UALUES(I) 

END DO 
RETURN 
END 


Figure 3-1: Subroutine Using a Data Structure Argument 

Figure 3-2 is a typical example of an I/O system service. The program invokes SYS$QIOW 
to enable CTRL/C trapping. When the program runs, it prints an informational message 
whenever it is interrupted by a CTRL/C, and then it continues execution. 

PROGRAM TRAPC 
INCLUDE 7 ( $ S Y S S R U N A M ) 7 
INTEGER*4 TT.CHAN 
COMMON TT_CHAN 
CHARACTER*40 LINE 

C Assign the I/O channel. If unsuccessful stop 
C otherwise initialize the trap routine. 

ISTAT = SYS$ASSIGN ( 7 TT 7 »TT-CHAN * t) 

IF (.NOT. ISTAT) CALL LIB$ST0P(7.UAL< ISTAT) ) 

CALL ENABLE-CTRLC 
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C Read a line of input and echo it 

10 READ (5 t 7 (A) 7 * END = 999) LINE 
TYPE * , 'LINE READ: 7 ♦ LINE 
GO TO 10 
999 END 

SUBROUTINE ENABLE-CTRLC 
INTEGER*^ TT_CHAN »SYS$QIOW 
COMMON TT-CHAN 
EXTERNAL CTRLC-ROUT 

C Include I/O s v mbols 

INCLUDE 7 ($IODEF) 7 
INCLUDE 7 ($SYSSRUNAM) 7 

C Enable CTRL/C trapping and specify CTRLC-ROUT 
C as routine to be called when C T R L/C occurs 

ISTAT = S Y S $ 0 I 0 N ( »'/.UAL ( TT-CHAN ) t 

1 IOAL(IO$_SETMODE ♦ OR ♦ I0$M_CTRLCAST) t 
1 » » »CTRLC-ROUT » t’/.OALO) t t t) 

IF (♦NOT* ISTAT) CALL L I B $ S T 0 P ( 7. U A L ( ISTAT) ) 

RETURN 

END 

SUBROUTINE CTRLC-ROUT 
PRINT * > 7 CTRL-C pressed 7 

CALL ENABLE-CTRLC 
RETURN 
END 

Figure 3-2: CTRL/C Trapping Example 


3.4 Object Code Examples 

The following sections present examples of FORTRAN calls and their corresponding object 
code (as represented in MACRO). 

3.4.1 Argument-Passing Examples 

The format used in the following examples shows FORTRAN source code, followed by 
argument lists generated in object code. 

Example 1: 

FORTRAN Source Code: 

REAL X 

INTEGER J(10) 

CHARACTER*15 C 
CALL SUB(X»J(3) *C) 


3-12 


FORTRAN Call Conventions 






Object Code: 


ARGLST: ♦ LONG 3 

♦ADDR X 

♦ ADDR J + 8 

♦ADDR L$1 

5 Count 

! Address of X 

5 Address of J<3) 

? C descriptor address 

L$1: .WORD 15 

♦BYTE 14 

♦BYTE 1 

♦ADDR C 

5 Length of C 

» Character type code 

5 Scalar class code 

i Address of C 

This example shows how the compiler generates an argument list for the arguments speci¬ 
fied in the CALL statement. The compiler can initialize the addresses of real variable X 
and array element J(3) because they are explicitly specified in the CALL statement. Simi¬ 
larly, the compiler has enough information to generate an initialized descriptor for the 
character string C. 

Example 2: 

FORTRAN Source Code: 


REAL X(10) 

CHARACTER*15 C 

CALL SUB(X( I ) »C(J:K ) ) 


Object Code: 


ARGLST: .LONG 2 

♦LONG 0 

♦ADDR L$1 

5 C o u n t 

5 X(I) initialized at run time 
! C(J:K) descriptor address 

L$1: .WORD 0 

♦BYTE 14 

♦BYTE 1 

♦LONG 0 

? C(J:K) length > set at run time 

5 Character type code 

5 Scalar class code 

? Base address of C(J:K )t set at 

5 run t i m e 

Run-Time Argument List Initialization Code: 

M00L I»R0 ! 

M00AF X-4CR0]>ARGLST+4 I 

SUBL3 #1 *Jt R0 i 

SUBL3 R0 >K »R1 i 

M00W R1 »L$1 i 

1 

M00AB CCRO]»L $ 1 + 4 ■ 

CALLG ARGLST »SUB ! 

i Compute address of X(I) and 

1 store it in the argument list 

! Compute the length of C(J:K) 

i 

I Store length of C(J:K) in argument 

! list 

I Store base address of C(J:K) in 

i argument list 

I Call subroutine SUB 


In this example, the FORTRAN source code defines a real array X, comprising 10 ele¬ 
ments, and a character variable C, comprising 15 elements. The actual arguments passed 
to subroutine SUB are the Ith element of array X and the substring C(J:K). The compiler 
generates an argument list consisting of three longwords: the first is the count and the 
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next two are the address of the Ith element of X and the address of the descriptor of substr¬ 
ing C(J:K). Note that the addresses of X(I) and C(J:K) and the length of C(J:K) are initial¬ 
ized to zero because these values are unknown at compile time. 

3.4.2 Examples of Argument List Built-In Functions 

The following examples show the FORTRAN source code, followed by the generated object 
code. 

Example 1: %VAL 
FORTRAN Source Code: 

CALL SUB< 4 tXV ALCG) »Z.OAL< - 1 ) »‘£OAL ( ZEXT ( - 1 ) ) ) 

Object Code: 

ARGLST: .LONG 4 

♦ADDR C0N4 
♦LONG G 

♦LONG FFFFFFFF 
♦LONG OOOOFFFF 

C0N4: .LONG 4 

As shown, the compiler generates an address for the constant 4 in the first entry, but gener¬ 
ates the actual value (6) in the following entry. Note that the constants are placed in read¬ 
only storage so that any attempt to change the value of a constant causes an access 
violation. 

Example 2: %REF 

FORTRAN Source Code: 

CHARACTER*10 C »D 
CALL SUB(C>ZREF(D)) 

Object Code: 

ARGLST: .LONG 2 

♦ADDR L$1 
♦ADDR D 

L$ 1 : .WORD 10 

♦BYTE 14 
♦BYTE 1 
♦ADDR C 

As shown, the argument list entry for D is the address of D. The compiler does not generate 
a descriptor for D, as it does for C, even though C and D are both specified in the source 
program as character variables. 


; C o u n t 

5 Address of C descriptor 
5 Address of D 

? Length 
5 Type code 
i Class code 
5 Address 


5 Count 

5 Address of constant 
5 value 

5 SiSn-extended u a 1ue 
; Zero-extended value 
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Example 3: %DESCR 

FORTRAN Source Code: 

CALL SUB(X»Z.DESCR(X> ) 

Object Code: 


ARGLST: 

♦ LONG 

2 

5 Connt 



♦ ADDR 

X 

? Address of 

X 


♦ ADDR 

L$ 1 

5 Address of 

X 

L$ 1 : 

♦ WORD 

a 

» Length 



♦ BYTE 

10 

i Type code 



♦ BYTE 

i 

5 Class code 



♦ ADDR 

X 

? Address 



In this example, the first argument list entry contains an address and the second entry 
contains a pointer to a descriptor. 


3.4.3 Character Function Example 

The following example illustrates how character function argument lists are generated. 
FORTRAN Source Code: 

CHARACTER*10 C »D 
D = C<I *J) 


Object Code: 




ARGLST: 

♦LONG 3 

5 Count 



♦ADDR L$1 

? Address of function 

descriptor 


♦ADDR I 

? Address of I 



♦ADDR J 

5 Address of J 


L$ 1 : 

♦WORD 10 

? Length 



♦BYTE 14 

5 Type code 



♦BYTE 1 

5 Class code 



♦LONG 0 

5 Address 


SUBL2 

#10 tSP 

? Allocate space for 

10 characters 

MOOL 

SP »L$1+4 

? Set address 


CALLG 

ARGLST fC 

! Call function C 


M00C3 

#10*(SP) tQ 

? Moue result to D 


MOOL 

R 1 ,SP 

? Remove result from 

stacK 


In this example, an additional argument list entry is allocated (the descriptor of the return 
value of the character function C). 
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Chapter 4 

Using VAX Record Management Services 


This chapter describes how to call VAX Record Management Services (RMS) directly from 
FORTRAN programs. VAX RMS is used by all utilities and VAX native mode languages 
for their I/O processing. In this way, all of these utilities and user programs written in 
native mode languages can access files efficiently, flexibly, with device independence, and 
taking full advantage of the capabilities of the underlying VMS operating system. 

You need to know the basic concepts concerning files on VMS systems and calling system 
services before reading this chapter. In particular, you should be familiar with the basic 
file concepts covered in Programming in VAX FORTRAN , and Introduction to VAX 
Record Management Services. You also need to know the system service calling conven¬ 
tions covered in Chapter 3 of this manual. After reading this chapter, you can also take 
advantage of the material in the VAX Record Management Services Tuning Guide , which 
covers more areas of RMS in greater detail than this chapter. 

In addition, you should have access to the VAX Record Management Services Reference 
Manual. That manual, although not written specifically for FORTRAN users, is the defini¬ 
tive reference source for all information on the use of VAX RMS. This chapter will provide 
you with the understanding to read the VAX Record Management Services Reference Man¬ 
ual and translate its terminology to FORTRAN concepts and usage. 

In particular, after reading this chapter, you should read Chapters 1 and 2 of the VAX 
Record Management Services Reference Manual ; it explains many of the concepts intro¬ 
duced here in greater detail and provides a good introduction to the rest of the VAX Record 
Management Services Reference Manual. 

The easiest way to call RMS services directly from FORTRAN is to use a USEROPEN rou¬ 
tine. A USEROPEN routine is a subprogram that you specify in an OPEN statement that 
the FORTRAN Run Time Library (RTL) I/O support routines will call in place of the RMS 
services at the time a file is first opened for I/O. 

The advantage of using a USEROPEN routine is that the FORTRAN RTL will set up the 
RMS data structures on your behalf with initial field values that are based on parameters 
specified in your OPEN statement. This initialization usually eliminates most of the code 
needed to set up the proper input to RMS Services. As a result, you can use USEROPEN 
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routines to take advantage of almost all of the power of RMS without most of the declara¬ 
tions and initialization code normally required. Section 4.2 describes how to use USER- 
OPEN routines and gives examples. You should be familiar with the material in Section 
4.1 before reading Section 4.2. 

4.1 RMS Data Structures and Services 

This section introduces the RMS data structures and services and describes how to use 
them in FORTRAN programs. The first subsection describes the FAB, RAB, NAM, and 
XAB blocks and how to declare and use them. The second subsection describes the RMS 
system services and how to call them from FORTRAN. 

4.1.1 RMS Data Structures 

RMS system services have so many options and capabilities that it is impractical to use 
anything other than several large data structures to provide their arguments. You should 
become familiar with all of the RMS data structures before using RMS system services. 
The RMS data structures are used both to pass arguments to RMS services and to return 
information from RMS services to your program. In particular, an auxiliary structure, 
such as a NAM or XAB block, is commonly used explicitly to obtain information optionally 
returned from RMS services. 

The RMS data structures are: 

• The File Access Block, or FAB, used to describe files in general. 

• The Record Access Block, or RAB, used to describe the records in files. 

• The Name Block, or NAM, used to give supplementary information about the name of 
files beyond that provided with the FAB. 

• The Extended Attributes Blocks, or XABs. These are a family of related blocks that 
are linked to the FAB to communicate to VAX RMS any file attributes beyond those 
expressed in the FAB. 

The VAX Record Management Services Reference Manual describes each of these data 
structures in detail and describes how they are used in calls to RMS services. In this sec¬ 
tion, a brief overview of each block is given, describing its purpose and how it is manipu¬ 
lated in FORTRAN programs. 

In general, there are 6 steps to using the RMS control blocks in calls to RMS system 
services. 

1. Declare the structure of the blocks and the symbolic parameters used in them by 
including the appropriate definition modules from the FORTRAN-supplied 
default library FORSYSDEF.TLB. 

2. Declare the memory allocation for the blocks that you need with a RECORD 
statement. 
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3. Declare the system service names by including the module $SYSSRVNAM from 
FORS Y SDEF.TLB. 

4. Initialize the values of fields needed by the service you are calling. In MACRO, 
facilities are provided to initialize most of the fields in the RMS data structures to 
reasonable default values. This default initialization capability is not provided for 
FORTRAN programs. The structure definitions provided for these blocks in the 
FORSYSDEF modules described below provide only the field names and offsets 
needed to reference the RMS data structures. You must assign all of the field val¬ 
ues explicitly in your FORTRAN program. 

Two fields of each control block are mandatory; they must be filled in with the cor¬ 
rect values before they are used in any service call. These are the block id (BID, or 
COD, in the case of XABs) and the block length (BLN). These are checked by all 
RMS services to ensure that their input blocks have proper form. These fields are 
initialized automatically by the appropriate declaration macro for VAX MACRO 
users but must be assigned explicitly in your FORTRAN programs, unless you are 
using the control blocks provided by the FORTRAN RTL I/O routines, which ini¬ 
tialize all control block fields. See Table 4-1 for a list of the control field values 
provided by the FORTRAN RTL I/O routines. 

5. Invoke the system service as a function reference, giving the control blocks as 
arguments according to the specifications in the RMS reference manual. 

6. Check the return status to ensure that the service has completed successfully. 

See Section 4.1.2 for description of steps 5 and 6. Steps 1-4 are described for each 
type of control block in sections 4.1.1.2 to 4.1.1.5. 

4.1.1.1 Using FORSYSDEF Modules to Manipulate RMS Data Structures - The FORTRAN-sup- 
plied definition library FORSYSDEF.TLB contains the required FORTRAN declarations 
for all of the field offsets and symbolic values of field contents described in the VAX Record 
Management Services Reference Manual. The appropriate INCLUDE statement needed to 
access these declarations for each structure is described wherever appropriate in the text 
that follows. In general, you need to supply one or more RECORD statements to allocate 
the memory for the structures that you need. For information on manipulating FORTRAN 
records, refer to Chapter 14 of Programming in VAX FORTRAN . See Chapter 2 of the 
VAX Record Management Services Reference Manual for a description of the naming con¬ 
ventions used in RMS service calls. Only the convention for the PARAMETER declara¬ 
tions is described here. 

The FORSYSDEF modules contain several different kinds of PARAMETER declarations. 
They are distinguished from each other by the letter following the dollar sign (“$”) in their 
symbolic names. Each is useful in manipulating the field values, but the way they are used 
is different for each kind: 
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• The first kind are simple symbolic field values. These are identified by the presence of 
a “Cimmediately following the block prefix in their name. For example, the 
RAB$B_RAC field has 3 symbolic values, one each for sequential, keyed, and RFA 
access modes. The symbolic names for these values are RAB$C_SEQ, RAB$C_KEY, 
and RAB$C_RFA. You use these symbolic field values in simple assignment state¬ 
ments, for example: 

INCLUDE 7 ($RABDEF) 7 
RECORD /RABDEF/ MYRAB 


MYRAB.RAB$B_RAC = RAB$C_SEQ 


• The second kind use mask values to define bit offsets rather than explicit values. 
These are identified by the presence of a “M_” immediately following the block prefix 
in their name. For example, the FAB$L_FOP field is an INTEGER*4 field with the 
individual bits treated as flags. Each flag has a mask value for specifying a particular 
file processing option. For instance, the MXV bit specifies that RMS should maximize 
the version number of the file when it is created. The mask value associated with this 
bit has the name FAB$M_MXV. In order to use these parameters, you must use .AND. 
and .OR. to turn off and on specific bits in the field without changing the other bits. 
For example, to set the MXV flag in the FOP field, you would use the following pro¬ 
gram segment: 

INCLUDE 7 ($FABDEF) 7 
RECORD /FABDEF/ MYFAB 


MYFAB,FAB$L_FOP 


MYFAB,FAB$L_FOP ,0R, F A B $ M _ M X U 


The third and fourth kinds of symbolic field values are also used to define flag fields 
within a larger named field. These are identified by the “S_” and “V_” values immedi¬ 
ately following the block prefix in their names. The “S_” form of the name defines the 
size of that flag field (usually the value 1, for single bit flag fields), and the “V_” form 
defines the bit offset from the beginning of the larger field. These forms of the names 
can be used with the symbolic bit manipulation functions to set or clear the fields 
without destroying the other flags. Thus, performing the same operation as the previ¬ 
ous example using the “V_” and “S_” flags would be done as follows: 
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INCLUDE 7 ($FABDEF ) 7 
RECORD /F ABDEF/ MYFAB 


MYFAB♦FAB$L_FO P = IBSET(MYFAB.FAB$L_FOP>FAB$Y_MXV) 


For most of the FAB, RAB, NAM, and XAB fields that are not supplied using symbolic 
values, you will need to supply sizes or pointers. For the sizes, you can use ordinary 
numeric constants or other numeric scalar quantities. For instance, to set the maximum 
record number into the FAB$L_MRN field, you could use the statement: 

MYFAB.FAB$L_MRN = 5000 

To supply the required pointers, usually from one block to another, you must use the %LOC 
built-in function to retrieve addresses. For example, to fill in the FAB$L_NAM field in a 
FAB block with the address of the NAM block that you want to use, you can use the follow¬ 
ing program fragment: 

INCLUDE 7 ($F ABDEF) 7 
INCLUDE 7 ($NAMDEF) 7 


RECORD /FABDEF/ MYFAB t /NAMDEF/ MYNAM 


MYFAB.FAB$L_NAM = XLOC(MYNAM) 

4.1.1.2 The File Access Block - The File Access Block (FAB) is used for calling the follow¬ 
ing services: 

SYS$OPEN 

SYS$CREATE 

SYS$CLOSE 

SYS$PARSE 

SYS$SEARCH 

S Y S$DISPLAY 

SYS$ENTER 

SYS$ERASE 

SYS$EXTEND 

SYS$REMOVE 

SYS$RENAME 

The purpose of the FAB is to describe the file being manipulated by these services. In addi¬ 
tion to the fields that describe the file directly, there are pointers in the FAB structure to 
auxiliary blocks used for more detailed information about the file. These auxiliary blocks 
are the Name (NAM) block, and one or more of the Extended Attributes (XAB) blocks. 
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To declare the structure and parameter values for using FAB blocks, include the 
$FABDEF module from FORSYSDEF. For example: 

INCLUDE 7 ($F ABDEF) 7 

To examine the fields and values declared, use the /LIST qualifier after the right parenthe¬ 
sis. Each field in the FAB is described at length in Chapter 5 of the VAX Record Manage¬ 
ment Services Reference Manual . 

If you are using a USEROPEN procedure, the actual allocation of the FAB is performed by 
the FORTRAN Run Time Library I/O support routines, and you only need to declare the 
first argument to your USEROPEN routine to be a record with the FAB structure. For 
example: 

Calling program: 


EXTERNAL MYOPEN 


□ PEN (UN IT = 8 * ♦♦♦ » USEROPEN = MYOPEN) 


Useropen routine: 

INTEGER FUNCTION MYOPEN(FABARG» RABARG * LUNARG) 
INCLUDE 7 ($F ABDEF) 7 


RECORD /F ABDEF/ FABARG 


Usually, you will only need to declare one FAB block. Sometimes, however, you need to use 
two different FAB blocks. For example the SYS$RENAME service requires two FAB 
blocks, one to describe the old file name and one to describe the new file name. In any of 
these cases, you can declare whatever FAB blocks you need with a RECORD statement. 
For example: 

INCLUDE 7 ($F ABDEF) 7 


RECORD /FABDEF/ OLDFAB» NEWFAB 
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When you use any of the above service calls without using a USEROPEN routine, you will 
need to initialize the required FAB fields in your program. The FAB fields required for each 
RMS service are listed in the description of that service in the VAX Record Management 
Services Reference Manual. In addition, most services fill in output values in the FAB or 
one of its associated blocks. These output fields are also described with the service descrip¬ 
tion. In the examples supplied in Chapter 3 of the VAX Record Management Services Ref¬ 
erence Manual , these initial field values are described as they would be used in MACRO 
programs, where the declaration macros allow initialization arguments. Thus, in each 
case where the MACRO example shows a field being initialized in a macro, you must have 
a corresponding initialization at run time in your program. 

For example, the Example 3-1 of the $CREATE macro in the VAX Record Management 
Services Reference Manual shows the use of the ALQ parameter for specifying the initial 
allocation size of the file in blocks. As described in the section on ALQ in Chapter 5, this 
parameter sets the FAB field FAB$L_ALQ. This means that to perform the same initial¬ 
ization in FORTRAN, you must supply FAB$L_ALQ field value by a run time assignment 
statement, for example: 

MYFAB*FAB$L_ALQ = 500 

The FAB$B_BID and FAB$B_BLN fields must be filled in by your program prior to their 
use in an RMS service call, unless they have already been supplied by the FORTRAN RTL 
I/O routines. You should always use the symbolic names for the values of these fields, for 
example: 

INCLUDE ' ($FABDEF) ' 


RECORD /FABDEF/ MYFAB 


MYFAB*FAB$B_BID = FAB$C_BID 
MYFAB*FAB$B_BLN = FAB$C_BLN 


STATUS = SYS$0 PEN( ♦ ♦ ♦ ) 


4.1.1.3 The Record Access Block - The Record Access Block (RAB) is used for calling the 
following services: 

SYS$CONNECT 
S Y S$DISCONNECT 
SYS$FIND 
SYS$GET 
SYS$PUT 
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SYS$DELETE 

S Y S$TRUNC ATE 

SYS$UPDATE 

SYS$FLUSH 

SYS$FREE 

SYS$NXTVOL 

SYS$RELEASE 

SYS$REWIND 

SYS$WAIT 

SYS$READ 

SYS$SPACE 

SYS$ WRITE 

The purpose of the RAB is to describe the record being manipulated by these services. The 
RAB contains a pointer to the FAB used to OPEN the file being manipulated, making it 
unnecessary for these services to have a FAB in in their argument lists. Also, a RAB can 
point to only one kind of XAB, a terminal XAB. 

To declare the structure and parameter values for using RAB blocks, include the 
$RABDEF module from FORSYSDEF. For example: 

INCLUDE 7 ($RABDEF) 7 

To examine the fields and values declared, use the /LIST qualifier after the right parenthe¬ 
sis. Each field in the RAB is described at length in Chapter 7 of the VAX Record Manage¬ 
ment Services Reference Manual. 

If you are using a USEROPEN procedure, the actual allocation of the RAB is performed by 
the FORTRAN Run Time Library I/O support routines, and you only need to declare the 
second argument to your USEROPEN routine to be a record with the RAB structure. For 
example: 

Calling program: 


EXTERNAL NYOPEN 


□ PEN (UN IT = 8 t » USEROPEN = MYOPEN) 
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Useropen routine: 

INTEGER FUNCTION MYOPEN(FABARG* RABARG * LUNARG) 

INCLUDE 7 < $RABDEF ) 7 

RECORD /RABDEF/ RABARG 


If you need to access the RAB used by the FORTRAN I/O system for one of the open files in 
your program, you can use the FOR$RAB system function. You can use FOR$RAB even if 
you didn’t use a USEROPEN routine to open the file. The FOR$RAB function takes a sin¬ 
gle argument, the unit number of the open file for which you to obtain the RAB address. 
The function result is the address of the RAB for that unit. When you use the FOR$RAB 
function in your program, you should declare it to be INTEGER if you assign the result 
value to a variable. If you do not, your program will assume that it is a REAL function and 
will perform an improper conversion to INTEGER. To use the result of the FOR$RAB call, 
you must pass it to a subprogram as an actual argument using the %VAL built-in function. 
This allows the subprogram to access it as an ordinary FORTRAN record argument. For 
example, the main program for calling a subroutine to print the RAB fields could be coded 
as follows: 

INTEGER RABADR t FOR$RAB 


OPEN(UN IT=14 * FILE= 7 TEST*DAT 7 t STATUS= 7 OLD 7 ) 


RABADR = FQR$RAB(14) 


CALL DUMPRAB ('/.UAL ( RABADR ) ) 


If you need to access other control blocks in use by the RMS services for that unit, you can 
obtain their addresses using the link fields they contain. For example: 
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SUBROUTINE DUMPRAB(RAB) 


INTEGER*^ FABADR 
INCLUDE 7 ($RABDEF) 7 
RECORD /RABDEF/ RAB 


FABADR = RAB♦RAB$L_F AB 


CALL DUMPFABdUAL(FABADR) ) 


In this example, the routine DUMPRAB obtains the address of the associated FAB by 
referencing the RAB$L_FAB field of the RAB. Other control blocks associated with the 
FAB, such as the NAM and XAB blocks, can be accessed using code similar to this 
example. 

Usually, you will only need to declare one RAB block. Sometimes, however, you may need 
to use more than one. For example, the multistream capability of RMS allows you to con¬ 
nect several RABs to a single FAB. This allows you to simultaneously access several 
records of a file, keeping a separate context for each record. In any case, you can declare 
whatever RAB blocks you need with a RECORD statement. For example: 

INCLUDE 7 ($RABDEF) 7 


RECORD /RABDEF/ R AB 1 » RABARRAY(IO) 

When you use any of the above service calls without using a USEROPEN routine, you will 
need to initialize the required RAB fields in your program. The RAB fields required for 
each RMS service are listed in the description of that service in the VAX Record Manage¬ 
ment Services Reference Manual. In addition, most services fill in output values into the 
RAB. These output fields are also described with the service description. In the examples 
supplied in Chapter 4 of the VAX Record Management Services Reference Manual , these 
initial field values are described as they would be used in MACRO programs, where the 
declaration macros allow initialization arguments. Thus, in each case where the MACRO 
example shows a field being initialized in a declaration macro, you must have a corre¬ 
sponding initialization at run time in your program. 
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For example, the Example 4-3 in the VAX Record Management Services Reference Manual 
shows the use of the RAC parameter for specifying the record access mode to use. In the 
example, sequential access mode is used. As described in the section on the RAC field in 
Chapter 7, this parameter sets the RAB$B_RAC field to the value RAB$C_SEQ. This 
means that to perform the same initialization in FORTRAN, you must supply RAC field 
values by a run time assignment statement, for example: 

MYRAB.RAB$B_RAC = RAB$C_SEQ 

The RAB$B_BID and RAB$B_BLN fields must be filled in by your program prior to their 
use in an RMS service call, unless they have been supplied by the FORTRAN RTL I/O 
routines. You should always use the symbolic names for the values of these fields, for 
example: 

INCLUDE / ($RABDEF) 7 


RECORD /RABDEF/ MYRAB 


MYRAB.RAB$B_BID = RAB$C_BID 
MYRAB.RAB$B_BLN = RAB$C_BLN 


STATUS = SYS$CONNECT(MYRAB) 


4.1.1.4 The Name Block - The Name Block (NAM) can be used with the FAB in most FAB 
related services in order to supply to or receive from RMS more detailed information about 
a file name. The NAM block is never given directly as an argument to an RMS service, to 
supply it you must link to it from the FAB. See Section 4.1.1.1 for an example of this. 

To declare the structure and parameter values for using NAM blocks, include the 
$NAMDEF module from FORSYSDEF. For example: 

INCLUDE 7 ($NAMDEF) 7 

To examine the fields and values declared, use the /LIST qualifier after the right parenthe¬ 
sis. Each field in the NAM is described at length in Chapter 6 of the VAX Record Manage¬ 
ment Services Reference Manual. 

If you are using a USEROPEN procedure, the actual allocation of the NAM is performed 
by the FORTRAN Run Time Library I/O support routines. Because the NAM block is 
linked to the FAB, it is not explicitly given in the USEROPEN routine argument list. 
Thus, to access the NAM, you need to call a subprogram, passing the pointer by value and 
accessing the NAM in the subprogram as a structure. For example: 
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Calling program: 


EXTERNAL MYOPEN 

OPEN (UN IT = 8 * . .. » USEROPEN = MYOPEN) 

Useropen routine: 

INTEGER FUNCTION MYOPEN<FABARG» RABARG > LUNARG) 

INCLUDE 7 ($FABDEF ) 7 

RECORD /FABDEF/ FABARG 

CALL NAMACCESS(ZUAL(FABARG.FAB$L_NAM)) 

NAM accessing routine: 

SUBROUTINE NAMACCESS(NAMARG) 

INCLUDE 7 ($NAMDEF) 7 

RECORD /NAMDEF/ NAMARG 

♦ 

IF (NAMARG.NAM*B_ESL .GT. 132) GO TO 100 

Usually, you only need to declare one NAM block. You can declare whatever NAM blocks 
you need with a RECORD statement. For example: 
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INCLUDE 7 ($NAMDEF) 7 


RECORD /NAMDEF/ NAM 1 » NAM2 

Most often, you use the NAM block to pass and receive information about the components 
of the file specification, such as the device, directory, file name, and file type. For this rea¬ 
son, most of the fields of the NAM block are CHARACTER strings and lengths. Thus, 
when using the NAM block, you should be familiar with the argument passing mecha¬ 
nisms for CHARACTER arguments described in Section 3.3.4.3. 

The NAM$B_BID and NAM$B_BLN fields must be filled in by your program prior to their 
use in an RMS service call, unless they have been supplied by the FORTRAN RTL I/O 
routines. You should always use the symbolic names for the values of these fields, for 
example: 

INCLUDE 7 ($NAMDEF) 7 


RECORD /NAMDEF/ MYNAM 


MYNAM.NAM$B_BID = NAM$C_BID 
MYNAM»NAM$B_BLN = NAM$C_BLN 


4.1.1.5 The Extended Attributes Blocks - The Extended Attribute Blocks (XABs) are a 
whole family of related structures for passing and receiving additional information about 
files to RMS Services. There are nine different kinds of XABs, as follows: 

1. Allocation Control (XABALL) 

2. Date and Time (XABDAT) 

3. File Header Characteristics (XABFHC) 

4. Journaling (XABJNL) 

5. Key Definition (XABKEY) 

6. Protection (XABPRO) 

7. Revision Date and Time (XABRDT) 

8. Summary (XABSUM) 

9. Terminal (XABTRM) 
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The XABs are described in Chapters 8 through 16 of the VAX Record Management Ser¬ 
vices Reference Manual. The XABs are generally smaller and simpler than the FAB, RAB, 
and NAM blocks because each describes information about a single aspect of the file. They 
are all optional; you use only the ones that you need for any given call to an RMS service 
routine. Often the XAB fields override the corresponding fields in the FAB. For example, 
the allocation XAB describes the file’s block allocation in more detail than the 
FAB$L_ALQ field can. For this reason, XAB$L_ALQ (the allocation field in the XABALL 
structure) always overrides the FAB$L_ALQ value. 

The XABs used for any given RMS service call are connected to the FAB in a linked list. 
The head of the list is the FAB$L_XAB field in the FAB. This field contains the address of 
the first XAB to be used. Each successive XAB in the list links to the next using the 
XAB$L_NXT field. This field contains the address of the next XAB in the list. The order of 
the XABs in the list does not matter, but each kind of XAB must not appear more than once 
in the list. 

The only kind of XAB that can be connected to a RAB instead of a FAB is the terminal 
XAB. It is linked to with the RAB$L_XAB field. This is needed because the terminal con¬ 
trol information is dynamic and potentially changes with each record operation 
performed. 

To declare the structure and parameter values for using the different XAB blocks, include 
the appropriate XAB definition module from FORSYSDEF. The individual module names 
are given in the list given previously in this section. Also, because the XABs are a family of 
related control blocks, you also need to include the $XAB module from FORSYSDEF.TLB 
in order to declare the fields common to all XABs. For example, to declare the fields used in 
the Date and Time XAB, use the following declarations: 

INCLUDE '($ X A B D A T) 7 
INCLUDE 7 ($ X A B) 7 

To examine the fields and values declared, use the /LIST qualifier after the right parenthe¬ 
sis. Each field of each of the XABs is described in detail in Chapters 8 through 16 in the 
VAX Record Management Services Reference Manual. 

If you are using a USEROPEN procedure, the actual allocation of the XABs used by the 
open operation is performed by the FORTRAN Run Time Library I/O support routines. 
Because the XAB blocks are linked to the FAB, it is not explicitly given in the USEROPEN 
routine argument list. Thus, to access the XABs, you need to call a subprogram and pass a 
pointer to it using the %VAL built-in function. For an example of this method, see Section 
4.1.1.3. 

To actually allocate space for a XAB block in your program, you need to declare it with a 
RECORD statement, for example: 
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INCLUDE 7 < $ X A B D A T ) 7 
INCLUDE 7 ($ X A B P R 0) 7 


RECORD /XABDATDEF/ MYXABDAT t /XABPRODEF/ MYXABPRO 


For each XAB that you declare in your program, you must supply the correct COD and 
BLN fields explicitly. These field offsets are common to all XABs and are contained in the 
$XAB module in FORSYSDEF.TLB. The block id and length is unique for each kind of 
XAB and the symbolic values for them are contained in the separate XAB declaration 
modules in FORSYSDEF.TLB. For example, to properly initialize a Date and Time XAB, 
you could use the following code segment: 

INCLUDE 7 ($XABDAT ) 7 

INCLUDE 7 ($ X A B) 7 

RECORD /XABDATDEF/ MYXABDAT 


MYXABDAT.XAB$B_COD = XAB$C_DAT 
MYXABDAT.XAB$B_BLN = XAB$C_DATLEN 


4.1.2 RMS Services 

In general, you need to do the same things when calling an RMS service as you need to do 
when calling any VMS service, that is, declare the name, pass arguments, and check sta¬ 
tus values. (See Section 3.3 for general information on calling VMS system services.) How¬ 
ever, RMS services have some additional conventions and ease of use features that you 
should be aware of. For a more complete description of each RMS service, refer to part IV of 
the VAX Record Management Services Reference Manual. 

4.1.2.1 Declaring RMS System Service Names - As with the other system services, you 
should use the $SYSSRVNAM module in FORSYSDEF to declare the names of all of the 
RMS services. For example: 

INCLUDE 7 <$SYSSRUNAM> 7 

This module contains comments describing each VMS system service, including all of the 
RMS services, and INTEGER*4 and EXTERNAL declarations for each. This will allow 
you to use these names in your programs without further declaration. 
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4.1.2.2 Arguments to RMS Services - See Section 3.3.4 for a general discussion of passing 
arguments to system services. Most RMS services require three arguments. The first is the 
control block to be used, generally a RAB or FAB, and is mandatory. The second and third 
arguments are the addresses of routines to be called if the RMS service fails or succeeds, 
and these are optional. Some RMS services take other arguments, but these services are 
rarely needed. You should always refer to the documentation for the specific service that 
you are calling for detailed information on its arguments. Most RAB and FAB fields are 
ignored by most RMS services. The documentation of each service in the VAX Record Man¬ 
agement Services Reference Manual describes which fields are input for that service and 
which are output, for each control block used. Services that take a FAB as an argument are 
called the File Control services. Services that take a RAB as an argument are called the 
Record Control services. You will generally need to use both when doing RMS I/O in your 
program. In general, fields that are not documented as required for input to a service are 
ignored and can be left uninitialized. The exceptions are the Block Id (BID or COD) and 
Block Length (BLN) fields; these must always be initialized. See the preceding sections 
about the respective blocks for examples of how to initialize these fields. 

The output of many RMS services provides the values required for input to other RMS 
services. For this reason, you usually only need to initialize a few fields in each block to 
their non-default values. This is especially true when using RMS blocks declared with the 
FORTRAN RTL I/O routines, for instance, when using USEROPEN routines or the 
FOR$RAB function. 

4.1.2.3 Checking Status from RMS Services - You should always invoke RMS services as 
functions, rather than calling them as subroutines (see Section 3.3.2 for a general discus¬ 
sion of this topic). It is particularly important to check the status of RMS services because 
they generally will not cause an error when the requested service fails. If the status is not 
checked immediately, the failure will go undetected until later in the program where it 
will be hard to diagnose. 

In most cases, you only need to check for success or failure by testing whether the returned 
status is true or false. Some services have alternate success status possibilities, and you 
should always check for these in cases where the program depends on the correct operation 
of the services. The RMS services have a unique set of status return symbols not used by 
any of the other VMS services. You should always use these symbols whenever you check 
the individual status values returned. To obtain the declarations for these symbols, 
include the $RMSDEF module from FORSYSDEF.TLB. For example: 

INCLUDE 7 ($RMSDEF) 7 

This statement will include declarations for all of the symbolic RMS return values in your 
program. 

The VAX Record Management Services Reference Manual documents, for each service, 
which symbolic values, both success and failure, can be returned from that service. Your 
program should always test each service result status against these symbolic values and 
take appropriate action when a failure status is detected. You should always declare status 
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variables as INTEGER*4 type in order to avoid unexpected numeric conversions. The rec¬ 
ommended action depends on whether you are using RMS services in a USEROPEN 
routine. 

In a USEROPEN routine, the FORTRAN RTL I/O routines that invoke your USEROPEN 
routine are expecting an RMS status as an output value. For this reason, you need to 
return the RMS status value as the function value — for both failure and success condi¬ 
tions. For example: 

INTEGER FUNCTION MYOPEN<FAB ,RAB»LUN) 


INCLUDE 7 <$SYSSRUNAM) 7 


Declare RMS service names 


MYOPEN = SYS$OPEN(FAB) 

IF (.NOT* MYOPEN) RETURN 


RETURN 

END 

In this case, if the SYS$OPEN service fails, it will return an error status into the function 
result variable MYOPEN. If the test of MYOPEN does not indicate success, the function 
will return the actual RMS status as its value. The RTL I/O routines will then signal the 
appropriate FORTRAN error normally, as if no USEROPEN routine had been used. If the 
SYS$OPEN call succeeds, the program will continue, and the RMS$_NORMAL success 
status will ultimately be returned to the FORTRAN RTL. This value will cause the OPEN 
statement that specifies MYOPEN to complete successfully. 

However, if you are not using a USEROPEN routine, your program needs to indicate the 
error status directly, unless it is prepared to deal with it. Often, the easiest way to indicate 
an error and issue a helpful message is to signal the RMS condition directly with 
LIB$SIGNAL or LIB$STOP. For example: 


INCLUDE 7 <$SYSSRUNAM> 7 
INTEGER*^ STATUS 


! Declare RMS service names 
! Declare a status variable 


STATUS = 5YS$GET(MYRAB) 

IF (.NOT. STATUS) CALL L I B$STOP ( 7.0 A L ( STATUS ) ) 

See Section 6.4 for more information on the use of LIB$SIGNAL and LIB$STOP. 
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4.1.2.4 Opening a File - To perform input or output operations on a file, your program 
must first open the file and establish an active RMS I/O stream. To open a file, your pro¬ 
gram generally needs to call either the SYS$CREATE or SYS$OPEN services, followed by 
the SYS$CONNECT service. When you use a FORTRAN OPEN statement without a 
USEROPEN routine, the FORTRAN RTL I/O routines do this for your program. 

SYS$OPEN and SYS$CREATE provide the following file opening options: 

• Use the SYS$OPEN service to open a file that should already exist. SYS$OPEN will 
return an error status if the file cannot be found. 

• Use the SYS$CREATE service to intentionally create a new file. 

• Use SYS$CREATE with the CIF bit in the FAB$L_FOP field to open a file that may or 
may not exist. The SYS$CREATE service will open the existing file, if one exists, or 
create a new one, if none exists. Use the SUP bit to force SYS$CREATE to create a 
new file even if one already exists. 

The value of the FAB$B_FAC field of the FAB indicates to RMS what record operations 
will be done on the file being opened. If a record operation that was not indicated by the 
FAC field (such as a SYS$PUT) is attempted, the record service will return a failure status 
and the operation will not be performed. This is an important file protection feature, it 
prevents you from accidentally corrupting a file when you use the wrong RMS service. 

The SYS$CONNECT service establishes an active I/O stream, using a RAB, to a file that 
has been previously opened by your program. RMS identifies all active I/O streams by a 
unique identifier, called the Internal Stream Identifier (IFI). This value is stored in the 
RAB$W_ISI field of the RAB for each active stream being processed. This field must 
always be zero when calling SYS$CONNECT. The SYS$CONNECT service initializes 
this field so that subsequent operations using that RAB can be uniquely identified. Under 
some circumstances, you can establish more than one simultaneously active I/O stream to 
the same file. See the VAX Record Management Services Reference Manual for more infor¬ 
mation on this topic. 

4.1.2.5 Closing a File - To close a file, use the SYS$CLOSE service. This terminates all 
active I/O streams under way on that file and frees all RMS resources being used for 
processing that file. Use the SYS$DISCONNECT service if you want to end one active I/O 
stream, but want to continue processing the file using another stream. This service sets the 
RAB$W_ISI value to zero so that the RAB can be reused for another stream. 

4.1.2.6 Writing Data - To write data to a file, use the SYS$PUT or SYS$WRITE service. 
Your program must set the PUT bit in the FAB$B_FAC field when the file is opened; other¬ 
wise, the service attempting the write operation will fail. 
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You use the SYS$PUT service when you want to write data in record mode (the default). In 
this mode, RMS buffers data automatically and performs the actual output operation for a 
whole group of records at a time. This is the mode used for all FORTRAN WRITE state¬ 
ments. Because most utilities and programs can read data written in record mode, this 
mode should be used whenever a general program or utility will be processing the data 
being written. 

You use the SYS$WRITE service when you want to bypass the record management capa¬ 
bilities of RMS and write blocks of data directly to the device without additional buffering. 
This mode is called block mode I/O and is generally much faster and uses fewer CPU 
resources than record mode. For this reason, it is the preferred mode for writing large 
amounts of unformatted data to a device quickly. You should use block mode only when the 
program that needs to read the data can also use block mode, or use some other means to 
guarantee that you can access the data being written. For instance, it is not generally pos¬ 
sible to read data written with SYS$WRITE using ordinary FORTRAN READ state¬ 
ments. You should read the special restrictions on using this mode in the VAX Record 
Management Services Reference Manual before using SYS$WRITE because this service 
may be subject to device dependencies that record mode is not. 

4.1.2.7 Reading Data - To read data from a file, use the SYS$GET or SYS$READ service. 
Your program must set the GET bit in the FAB$B_FAC field when the file is opened; other¬ 
wise, the service attempting the read operation will fail. 

You use the SYS$GET service when you want to read data in record mode (the default). In 
this mode, RMS buffers data automatically and performs the actual input operation for a 
whole group of records at a time. This is the mode used for all FORTRAN READ state¬ 
ments. This mode should be used whenever the program or utility that wrote the data used 
record mode, unless your reading program can buffer and deblock the data itself. 

You use the SYS$READ service when you want to bypass the record management capabil¬ 
ities of RMS and read blocks of data directly from the device without buffering or deblock¬ 
ing. This mode is called block mode I/O and is generally much faster and uses fewer CPU 
resources than record mode. For this reason, it is the preferred mode for reading large 
amounts of unformatted data from a device quickly. You should use SYS$READ only when 
the data was written using a utility or program that wrote the data in block mode. If the 
file was written using record mode, RMS control information may be intermixed with the 
data, making it difficult to process. You should read the special restrictions on using this 
mode in the VAX Record Management Services Reference Manual before using 
SYS$WRITE, however, because this service may be subject to device dependencies that 
record mode is not. 

4.1.2.8 Other Services - RMS provides many other file and record processing services 
beyond just Opening, Closing, Reading and Writing. Other file processing services include: 

• SYS$PARSE and SYS$SEARCH, which are used to process wildcard and incomplete 
file specifications and search for a sequence of files to be processed 

• SYS$DISPLAY, which is used to retrieve file attribute information 
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• SYS$ENTER, which inserts a file name into a directory file 

• SYS$ERASE, which deletes a file and removes the directory entry used to specify it 

• SYS$EXTEND, which increases the amount of disk space allocated to the file 

• SYS$REMOVE, which removes directory entries for a file 

• SYS$RENAME, which removes a directory entry for a file and inserts a new one in 
another directory 

Other record processing services include: 

• SYS$FIND, which positions the record stream at the desired record for later reading 
or writing 

• SYS$DELETE, which deletes a record from the file 

• SYS$TRUNCATE, which truncates a file after a given record 

• SYS$UPDATE, which updates the value of an existing record 

• SYS$SPACE, which skips over one or more blocks in block I/O mode. 

For complete descriptions of these and other RMS services, refer to the VAX Record Man¬ 
agement Services Reference Manual. 

4.2 User-Written Open Procedures 

The USEROPEN keyword in a FORTRAN OPEN statement provides you with a way to 
access VAX RMS facilities that are otherwise not available to FORTRAN programs. 

The USEROPEN keyword specifies a user-written external procedure (USEROPEN pro¬ 
cedure) that controls the opening of a file. It has the form: 

USEROPEN = procedure-name 

where: 

procedure-name 

is the symbolic name of a user-written open procedure. 

The procedure name must be declared in an EXTERNAL statement. 

When an OPEN statement — with or without the USEROPEN keyword — is executed, the 
Run-Time Library uses the OPEN statement keywords to establish the VAX RMS File 
Access Block (FAB) and the Record Access Block (RAB), as well as its own internal data 
structures. If a USEROPEN keyword is included in the OPEN statement, the Run-Time 
Library then calls your USEROPEN procedure instead of opening the file according to its 
normal defaults. The procedure can then provide additional parameters to VAX RMS and 
can obtain results from VAX RMS. 
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In order, the three arguments passed to a user-written open procedure by the Run-Time 
Library are: 

• The address of the FAB 

• The address of the RAB 

• The address of a longword containing the unit number 

Using this information, your USEROPEN procedure can then perform the following 
operations: 

• Modify the FAB and/or RAB (optional). 

• Issue SYS$OPEN and SYS$CONNECT functions or SYS$CREATE and 
SYS$CONNECT functions when FORTRAN I/O will be performed (required). Your 
USEROPEN procedure should invoke the RMS SYS$OPEN routine if the file to be 
opened already exists (STATUS = 'OLD') or should call the RMS SYS$CREATE rou¬ 
tine for any other file type (STATUS= 'NEW 1 , 'UNKNOWN 1 , or not specified). 

• Check status indicators returned by RMS services (required). Your procedure should 
return immediately if an RMS service returns a failure status. 

• Obtain information returned by RMS in the FAB and/or RAB by storing FAB and/or 
RAB values in program variables (optional). 

• Return a success or failure status value to the Run-Time Library (required). The RMS 
services SYS$CREATE, SYS$OPEN, and SYS$CONNECT return status codes. 
Thus, it is not necessary to set a separate status value as the procedure output if exe¬ 
cution of one of these macros is the final step in your procedure. 

For more information about the FAB and RAB, see the VAX Record Management Services 
Reference Manual. 

4.2.1 Examples of USEROPEN Routines 

Example 1: 

The following FORTRAN OPEN statement either creates a 1000-block contiguous file or 
returns an error. (The default VAX FORTRAN interpretation of the INITIALSIZE 
keyword is to allocate the file contiguously on a best-effort basis, but not to generate an 
error if the space is not completely contiguous.) 

EXTERNAL CREATE_CONT I G 

OPEN (UN I T= 1 0 t FILE = ' DAT A ' * STATUS = ' NEW ' t 
1 INITIALSIZE=1000» USEROPEN=CREATE.CONTIG) 

User-written open procedures are often coded in BLISS or MACRO; however, with VAX 
FORTRAN’S record handling capability, they can also be coded in FORTRAN. 

The following function creates a file after setting the RMS FOP bit (FAB$V_CTG) to spec¬ 
ify contiguous allocation. 
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C UO PEN 1 

C 

C Program to demonstrate the use of a simple USEROPEN routine 

C 

PROGRAM UO PEN 1 
EXTERNAL CREATE-CONTIG 

C OPEN the file specify ins the USEROPEN routine 

C 

OPEN < UN IT=10 » FILE= , DATA / » ST ATUS= ' NEW ' # 

1 INITIALSIZE=1000 » USEROPEN = CREATE_CONTIG) 

STOP 

END 

C CREATE-CONTIG 

C 

C Sample USEROPEN function to force RMS to allocate contiguous 

C blocks for the initial creation of a file. 

C 

INTEGER FUNCTION CREATE-CONTIG(FAB#RAB»LUN) 


Re^uired 

declarations 



INCLUDE 

' ($F ABDEF) 7 

! FAB St 

ructure 

INCLUDE 

' ($RABDEF) ' 

! RAB St 

ructure 

INCLUDE 

' ( $ S Y S S R U N A M ) ' 

! System 

service name declarations 


RECORD /FABDEF/ FAB » /RABDEF/ RAB 

C Clear the "ContiSuous-best-trv" bit t set the "Contiguous" bit 

C 

FAB.FAB$L_FOP = F AB.FAB$L_FO P .AND. .NOT. FAB$M_CBT 
FAB.FAB$L_FOP = FAB♦FAB$L_FOP .OR. FAB$M_CTG 

C Perform the create and connect# and return status 

C 

CREATE-CONTIG = SYS$CREATE(FAB) 

IF (.NOT. CREATE-CONTIG) RETURN 
CREATE-CONTIG = SYS$CONNECT(RAB) 

RETURN 

END 

Example 2: 

The following example shows the relationship between a FORTRAN function and a 
USEROPEN procedure. In this case, the USEROPEN keyword on the OPEN statement 
specifies the name of a FORTRAN procedure that permits use of the VAX RMS variable- 
with-fixed-length-control (VFC) record format feature. This feature is used here to obtain 
a text editor’s line sequence numbers that are prefixed to file records. 

The FORTRAN program: 
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C Function to retrieve text editor fi1e s t with line numbers 
C Example of USEROPEN Keyword of OPEN statement 

INTEGER FUNCTION SOSOPEN(UN IT-NUMBER» FILENAME) 

CHARACTER FILENAME***) 

INTEGER*2 LINE-NUMBER*0:90) 

INTEGER*^ UNIT-NUMBER t SUCCESS-CODE 
EXTERNAL GET_CNTRL_FLD 
COMMON /LINE_SEOS/LINE_NUMBER 

C Perform the open 

OPEN *UNIT = UNIT_NUMBER * FILE = FILENAME t STATUS='OLD' t 
1 USEROPEN=GET_CNTRL_FLD» IOSTAT=SUCCESS-CODE) 

SOSOPEN = SUCCESS-CODE 

RETURN 

END 

The USEROPEN procedure: 

INTEGER FUNCTION GET_CNTRL_FLD <FAB »RAB > LUN ) 

INCLUDE ' ($SYSSR0NAM) ' 

INCLUDE ' ($FABDEF) ' 

INCLUDE ' ($RABDEF) ' 

RECORD /$FABDEF/ FAB 
RECORD /$RABDEF/ RAB 
INTEGER*^ LUN t STATUS 
INTEGER*2 LINE-NUMBER (0:99) 

COMMON /LINE-SEOS/ LINE-NUMBER 

C Set size of header field into FAB 

FAB♦FAB$B_FSZ = 2 

C Set address into RAB 

RAB♦RAB$L_RHB = 1L0C *LINE-NUMBER(LUN)) 

C Perform the open 

STATUS = SYS$OPEN * FAB) 

C If opened oK > connect stream to file 

IF (STATUS) STATUS = SYS$CONNECT (RAB) 

C Return status 


GET_CNTRL_FLD = STATUS 

RETURN 

END 
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The file is created with the VFC record type. It uses the 2-byte fixed control field to store a 
16-bit unsigned integer. To access this control field from FORTRAN, a USEROPEN proce¬ 
dure must tell VAX RMS the size of the field it wants (FAB$B_FSZ) and the location of a 
variable in which to place the line number when a record is read (RAB$L_RHB). 

The USEROPEN procedure in this example, GET_CNTRL_FLD, determines which logi¬ 
cal unit is being opened and stores in the RAB the address of an element in the common 
array LINE-NUMBER. The USEROPEN procedure then opens the file and connects the 
record stream. If the operation is successful, a success status is returned from 
GET_CNTRL_FLD. Otherwise, a failure status is returned, causing the Run-Time 
Library to report that the operation failed. Each time a READ is done from the file, VAX 
RMS places the line number in the appropriate array element. (The LINE-NUMBER 
array has 100 elements, corresponding to the logical unit numbers 0 through 99.) 

4.2.2 RMS Control Structures 

Use of the USEROPEN keyword has some restrictions. The Run-Time Library constructs 
the following VAX RMS control structures before calling the USEROPEN procedure: 


FAB 

File Access Block 

RAB 

Record Access Block 

NAM 

Name Block 

XAB 

Extended Attributes Blocks 

ESA 

Expanded String Area 

RSA 

Resultant String Area 


A USEROPEN procedure should not alter the allocation of these structures, although it 
can modify the contents of many of the fields. Your procedure can also add additional XAB 
control blocks by linking them anywhere into the XAB chain. However, you must exercise 
caution when changing fields that have been set as a result of FORTRAN keywords, 
because the Run-Time Library may not be aware of the changes. For example, do not 
attempt to change the record size in your USEROPEN procedure; instead, use the 
FORTRAN keyword RECL. Always use a FORTRAN OPEN statement keyword if one is 
available. 

Although the FAB, RAB, and NAM blocks remain defined during the time that the unit is 
opened, the XAB blocks are present only until the file has been successfully opened. In 
addition, the locations of the ESA and RSA strings are changed after the file is opened. 
Therefore, your USEROPEN procedure should not store the addresses of the RMS control 
structures. Instead, have your program call FOR$RAB to obtain the address of the RAB 
once the file is opened and then access the other structures through the RAB. 

NOTE 

Future releases of the Run-Time Library may alter the use of some VAX RMS 
fields. Therefore, you may have to alter your USEROPEN procedures 
accordingly. 


4-24 Using VAX Record Management Services 




Table 4-1 shows which FAB, RAB, and XAB fields are either initialized before your USER- 
OPEN procedure is called or examined upon return from your USEROPEN procedure. All 
fields are initialized in response to FORTRAN OPEN statement keywords or default to 
zero. Fields labeled with a hyphen (-) are initialized to zero. Fields labeled with an asterisk 
(*) are returned by VAX RMS. 


Table 4-1: VAX RMS Fields Available with USEROPEN 


Field 

Name 

FORTRAN OPEN Keyword and Value 

FAB$L_ALQ 

Allocation quantity 

n if INITIALSIZE - n 

FAB$B_BKS 

Bucket size 

MIN(((MAX(RECL + 24,BLOCKSIZE) 

+ 511)/512),32) 

FAB$W_BLS 

Block size 

n if BLOCKSIZE = n 

FAB$L_CTX 

Context 

- Reserved for future use by DIGITAL 

FAB$W_DEQ 

Default file extension 
quantity 

nifEXTENDSIZE = n 

FAB$L_DEV 

Device characteristics 

* 

FAB$L_DNA 

Default file specification 
string address 

UNIT = nn 

Set to FOROnn.DAT or FORREAD.DAT, 
FORACCEPT.DAT, FORTYPE.DAT, or 
FORPRINT.DAT or DEFAULTFILE 

FAB$B_DNS 

Default file specification 
string size 

Set to length of default file specification string 

FAB$B_FAC 

File access 

READONLY 

Set to 0 if READONLY (RMS default) else to 
FAB$M_GET + FAB$M_PUT + FAB$M_UPD 
+ FAB$M_TRN + FAB$M_DEL 

FAB$L_FNA 

File specification string 
address 

FILE = filename if FILE present, else set to 
FOROnn, FOR$READ, FOR$ACCEPT, 
FOR$TYPE, FOR$PRINT, SYS$INPUT, or 
SYS$OUTPUT 

FAB$B_FNS 

File specification 

Set to length of file specification string size 
string 

FAB$L_FOP 

File processing options 


FAB$V_CBT 

Contiguous best try 

1 if INITIALSIZE = n 

FAB$V_CIF 

Create if nonexistent 

1 if STATUS = 'UNKNOWN' 

FAB$V_CTG 

Contiguous allocation 

- 

FAB$V_DFW 

Deferred write 

1 


(Continued on next page) 
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Table 4-1: (Cont.) VAX RMS Fields Available with USEROPEN 


Field 

Name 

FORTRAN OPEN Keyword and Value 

FAB$V_DLT 

Delete on close service 

Set at FORTRAN CLOSE, depending upon 
DISP keyword in OPEN or CLOSE, or STATUS 
keyword in CLOSE 

FAB$V_ESC 

Escape, nonstandard 
processing 

— 

FAB$V_INP 

Input, make this 
SYS$INPUT 

- 

FAB$V_KFO 

Known file open 

- 

FAB$V_MXV 

Maximize version number 

- 

FAB$V_NAM 

Name block inputs 

- 

FAB$V_NEF 

Not position at end of file 

0 if ACCESS = 'APPEND', else 1 

FAB$V_NFS 

Not file structured 

- 

FAB$V_OFP 

Output file parse 

- 

FAB$V_POS 

Current position (after 
closed file) 

- 

FAB$V_PPF 

Process permanent file 

- 

FAB$V_RCK 

Read check 

- 

FAB$V_RWC 

Rewind on close service 

- 

FAB$V_RWO 

Rewind on open service 

- 

FAB$V_SCF 

Submit command 

Set at FORTRAN CLOSE, depending upon file 
(when closed) 

FAB$V_SPL 

Spool to printer 

Set at FORTRAN CLOSE, depending upon 
DISP keyword in OPEN or CLOSE, or STATUS 
keyword in CLOSE 

FAB$V_SQO 

Sequential only 

1 if ACCESS = 'SEQUENTIAL' or 
'APPEND', else 0 

FAB$V_SUP 

Supersede 

- 

FAB$V_TEF 

Truncate at end-of-file 

- 

FAB$V_TMD 

Temporary, marked for 
delete 

1 if STATUS = 'SCRATCH', else 0 

FAB$V_TMP 

Temporary (file with no 
directory entry) 

- 

FAB$V_UFM 

User file mode 

- 

FAB$V_UFO 

User file open or create file 
only 

- 

FAB$V_WCK 

Write check 



(Continued on next page) 


4-26 Using VAX Record Management Services 








Table 4-1: (Cont.) VAX RMS Fields Available with USEROPEN 


Field 

Name 

FORTRAN OPEN Keyword and Value 

FAB$B_FSZ 

FAB$W_IFI 

FAB$L_MRN 

FAB$W_MRS 

Fixed control area size 

Internal file identifier 

Maximum record number 

Maximum record size 

* 

n if MAXREC = n 

If RECORDTYPE = 'FIXED' or 


ORGANIZATION = 'RELATIVE' then n, else 
0 


FAB$L_NAM 

Name block address 

Set to address of name block; both the 
expanded and resultant string areas are set up, 
but the related filename string is not 

FAB$B_ORG 

File organization 

FAB$C_IDX if ORGANIZATION = 
'INDEXED' 

FAB$C_REL if ORGANIZATION = 'RELA¬ 
TIVE' 

FAB$C_SEQ if ORGANIZATION = 
'SEQUENTIAL' or omitted 

FAB$B_RAT 

Record attributes 


FAB$V_FTN 

FORTRAN carriage 

1 if CARRIAGECONTROL = 'FORTRAN' 


control 


FAB$V_CR 

Print LF and CR 

1 if CARRIAGECONTROL = 'LIST' 

FAB$V_BLK 

Do not cross block 
boundaries 

1 if NOSPANBLOCKS 

FAB$B_RFM 

Record format 

FAB$C_FIX if RECORDTYPE = 'FIXED' 

FAB$C_VAR if RECORDTYPE = 'VARIA¬ 
BLE' 

FAB$C_VAR if RECORDTYPE = 'SEG¬ 
MENTED' 

FAB$C_STM if RECORDTYPE = 'STREAM' 

FAB$C_STMCR if RECORDTYPE = 
'STREAM_CR' 

FAB$C_STMLF if RECORDTYPE = 
'STREAM_LF' 

FAB$B_RTV 

Retrieval window size 

- 

FAB$L_SDC 

Spooling device 
characteristics 

* 

FAB$B_SHR 

File sharing 


FAB$V_PUT 

Allow other PUTs 

1 if SHARED 

FAB$V_GET 

Allow other GETs 

1 if SHARED 


(Continued on next page) 
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Table 4-1: (Cont.) VAX RMS Fields Available with USEROPEN 


Field 

Name 

FORTRAN OPEN Keyword and Value 

FAB$V_DEL 

Allow other DELETES 

1 if SHARED 

FAB$V_UPD 

Allow other UPDATES 

1 if SHARED 

FAB$V_NIL 

Allow no other operations 

- 

FAB$V_UPI 

User-provided interlock 

1 if SHARED and sequential organization 

FAB$V_MSE 

Multistream allowed 

- 

FAB$L_XAB 

Extended attribute block 
address 

The XAB chain always has a File Header Char¬ 
acteristics (FHC) extended attribute block in 
order to get longest record length 
(XAB$W_LRL). If the KEY = keyword is speci¬ 
fied, there will also be key index definition 
blocks present. DIGITAL may add additional 
XABs in the future. Your USEROPEN proce¬ 
dure may insert XABs anywhere in the chain 1 

RAB$L_BKT 

Bucket code 

— 

RAB$L_CTX 

Context 

- Reserved for future use by DIGITAL 

RAB$L_FAB 

FAB address 

Set to address of FAB 

RAB$W_ISI 

Internal stream ID 

* 

RAB$L_KBF 

Key buffer address 

Set to address of longword containing a 1 if 
ACCESS = 'DIRECT' 

RAB$B_KRF 

Key of reference 

0 

RAB$B_KSZ 

Key size 

- 

RAB$B_MBC 

Multiblock count 

If BLOCKSIZE = n, use (n + 51D/512 

RAB$B_MBF 

Multibuffer count 

n if BUFFERCOUNT = n 

RAB$L_PBF 

Prompt buffer address 

- 

RAB$B_PSZ 

Prompt buffer size 

- 

RAB$B_RAC 

Record access mode 

RAB$K_KEY if ACCESS = 'DIRECT' or 
'KEYED'; RAB$K_SEQ if ACCESS = 
'SEQUENTIAL' or ACCESS = 'APPEND' or 
ACCESS omitted 

RAB$L_RBF 

Record address 

Set later 

RAB$L_RHB 

Record header buffer 

- 


(Continued on next page) 
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Table 4-1: (Cont.) VAX RMS Fields Available with USEROPEN 


Field 

Name 

FORTRAN OPEN Keyword and Value 

RAB$L_ROP 

Record processing options 

- 

RAB$V_ASY 

Asynchronous 

- 

RAB$V_BIO 

Block I/O 

- 

RAB$V_CCO 

Cancel CTRL/O 

- 

RAB$V_CVT 

Convert to uppercase 

- 

RAB$V_EOF 

End-of-file 

1 if ACCESS = 'APPEND' 

RAB$V_KGE 

Key greater than or equal 
to 

- 

RAB$V_KGT 

Key greater than 

- 

RAB$V_LIM 

Limit 

- 

RAB$V_LOC 

Locate mode 

1 

RAB$V_NLK 

No lock 

- 

RAB$V_NXR 

Nonexistent record 

- 

RAB$V_PMT 

Prompt 

- 

RAB$V_PTA 

Purge type-ahead 

- 

RAB$V_RAH 

Read-ahead 

1 

RAB$V_RLK 

Read locked record allowed 

- 

RAB$V_RNE 

Read no echo 

- 

RAB$V_RNF 

Read no filter 

- 

RAB$V_TMO 

Timeout 

- 

RAB$V_TPT 

Truncate put 

1 

RAB$V_UIF 

Update if 

1 

RAB$V_ULK 

Manual unlocking 

- 

RAB$V_WBH 

Write-behind 

1 

RAB$W_RSZ 

Record size 

Set later 

RAB$B_TMO 

Timeout period 

- 

RAB$L_UBF 

User record area address 

Set later 

RAB$W_USZ 

User record area size 

Set later 


1. Note that VAX RMS does not allow multiple instances of the same type XAB. To be compatible 
with future releases of the Run-Time Library, your procedure should scan the XAB chain for 
XABs of the type to be inserted. If one is found, it should be used instead. 
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4.3 Example of Block Mode I/O Usage 

This example shows a complete application of calling the RMS block I/O services 
SYS$WRITE and SYS$READ directly from FORTRAN. The example is in the form of a 
complete program called BIO.FOR that writes out an array of REAL*8 values to a file 
using SYS$WRITE, closes the file, and then reads the data back in using SYS$READ oper¬ 
ations with a different I/O transfer size. This program consists of five routines: 


BIO 

BIOCREATE 

BIOREAD 

OUTPUT 

INPUT 


Main control program 

USEROPEN routine to create the file 

USEROPEN routine to open the file for READ access 

Function that actually outputs the array 

Function that actually reads the array and checks it 


Main Program — BIO 

C BIO.FOR 

C 

C Program to demonstrate the use of RMS Block I/O operations 

C from FORTRAN. 

C 

C 10-Ju1 - 1984 

C 

OPTIONS /EXTEND.SOURCE Q 

PROGRAM BIO 


C Declare the Use ropen routines as external 

C 

EXTERNAL BIOCREATE # BIOREAD 


C Declare status variable and functions# and unit numher 

C 

LOGICAL*/! STATUS# OUTPUT# INPUT 
INTEGER*/! IUN/1/ 

C Open the file 0 

C 

0PEN(UN IT =I UN # FILE= 'BIODEMO.DAT 7 # FORM= " UNFORMATTED / # STATUS* "NEW " » 
1 RECL=128# BLOCK SIZE = 512 # ORGAN IZAT I ON=" SEQUENT IAL" » IOSTAT=IOS# 

1 ACCESS= 'SEQUENTIAL ' # RECORDTYPE* 'FIXED ' # USEROPEN = BIOCREATE# 

1 INITIALSIZE=100) 

IF (IOS .NE. 0) STOP "Create failed" 0 

C Now perform the output 

C 

STATUS = OUTPUT (‘/.UAL(FOR$RAB( IUN) ) ) O 

IF (.NOT. STATUS) STOP "Output failed" 0 


4-30 


Using VAX Record Management Services 








c 

c 


c 

c 


c 

c 


c 

c 


c 

c 


Close the file for output 


CLOSE ( UN I T = 1 ) 

Confirm output complete 

TYPE * » 'Output complete » file closed 7 


Now open the file for input Q 

OPEN(UNIT=IUN t FILE='BI0DEM0*DAT 7 t FORM= 7 UNFORMATTED 7 t STATUS= "OLD 7 t 
1 IOST AT = I OS t USEROPEN=BIOREAD t DISP= 7 DELETE 7 ) 


IF (IOS ♦NE♦ 0) STOP 'Open for read failed 


Now read the file back 

STATUS = INPUT(ZUAL(FOR$RAB(IUN))) O 

IF (♦NOT♦ STATUS) STOP 'Input failed 7 Q 

Success * output that all is well 

STOP 'Correct completion of Block I/O demo 7 
END 


Notes: 

O The /EXTEND_SOURCE option is used to suppress the sequence number field. 

Q Most of the necessary OPEN options for the file are specified with OPEN state¬ 
ment parameters. This is recommended whenever an OPEN statement qualifier 
exists to perform the desired function because it allows the FORTRAN RTL I/O 
processing routines to issue appropriate error messages when an RMS routine 
returns an error status. 

Note the discrepancy between RECL and BLOCKSIZE in the first OPEN state¬ 
ment. Both keywords specify 512 bytes, but the number given for RECL is 128. 
This is because the unit implied in the RECL keyword is longwords for unformat¬ 
ted files. When using Block I/O mode, the blocksize used in the I/O operations is 
determined by the routine that actually does the operation. Thus, the OUTPUT 
routine actually transfers two 512-byte blocks at a time; whereas, the INPUT rou¬ 
tine actually transfers four 512-byte blocks at once. In general, the larger the 
transfers, the more efficiently the I/O is performed. The maximum I/O transfer size 
allowed by RMS is 65535 bytes. 

Q The error processing in this routine is very crude, the program simply stops with 
an indicator of where the problem occurred. In real programs, you should provide 
more extensive error processing and reporting functions. 
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O The function FOR$RAB is used to supply the appropriate RAB address to the 
OUTPUT and INPUT routines. The %VAL function is used to transform the 
address returned by the FOR$RAB function to the proper argument passing mech- 
anism so that the dummy argument RAB in INPUT and OUTPUT can be 
addressed properly. 

USEROPEN Functions - BIOCREATE and BIOREAD 

Aside from the normal declarations needed to define the symbols properly, the only inter¬ 
esting aspect to these routines is the setting of the BIO bit in the File Access field of the 
FAB. This is the only condition required for block I/O. If you wish to perform both block and 
record I/O on the file without closing it, you need to set the BRO bit as well. For more infor¬ 
mation on mixing block and record mode I/O, see the VAX Record Management Services 
Reference Manual. Note that the only difference between BIOCREATE and BIOREAD is 
the use of SYS$CREATE and SYS$OPEN services, respectively. 

C BIOCREATE 

C 

C USEROPEN routine to set the BlocK I/O bit 

C and create the BLOCK I/O demo file* 

C 

INTEGER FUNCTION BIOCREATE(FAB t RAB * LUN) 

INTEGER LUN 


C 

C 


C 

C 


C 

C 

C 


C 

C 


Declare the necessary interface names 

INCLUDE 7 ($F ABDEF) 7 
INCLUDE 7 ($RABDEF) 7 
INCLUDE 7 ( $ S Y S S R U N A M ) 7 

Declare the FAB and RAB blocks 

RECORD /FABDEF/ FAB t /RABDEF/ RAB 

Set the Block I/O bit in the FAC (GET 
bits set by RTL) 



and PUT 


FAB *FAB$B_FAC = FAB♦FAB$B_FAC .OR * FAB$M_BIO 

Now do the Create and Connect 

BIOCREATE = SYS$CREATE(FAB) 

IF (♦NOT♦ BIOCREATE) RETURN 
BIOCREATE = SYS$CONNECT(RAB) 

IF (.NOT* BIOCREATE) RETURN 
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C Nothin^ more to do at this point » Just return 

C 

RETURN 

END 


C 

C 

C 

C 

C 


C 

C 


BIOREAD 


USEROPEN routine to set 
open the B1o c K I/O demo 


the Block I/O bit and 
file for read ins 


INTEGER FUNCTION BIOREAD(FAB» RAB t LUN) 
INTEGER LUN 


Declare 


the necessary interface names 


INCLUDE '($F ABDEF) ' 
INCLUDE ' ($RABDEF) ' 
INCLUDE ' ($SYSSRUNAM) ' 


C Declare the FAB and RAB blocks 

C 

RECORD /FABDEF/ FAB * /RABDEF/ RAB 


C Set the Block I/O bit in the FAC (GET and PUT 

C bits set by RTL) 

C 

FAB♦FAB$B_FAC = F AB♦FAB$B_F AC .OR. FAB$M_BI 0 


C Now do the 
C 

BIOREAD = 
IF (♦NOT♦ 
BIOREAD = 
IF (.NOT. 


Open and Conn e c t 

SYS$OPEN(FAB) 
BIOREAD) RETURN 
SYS$CONNECT(RAB) 
BIOREAD) RETURN 


C NothinS more to do at this point * Just return 

C 

RETURN 

END 

OUTPUT Routine 


This routine initializes the array A and performs the SYS$WRITE operations. Beyond the 
normal RTL initialization, only the RSZ and RBF fields in the RAB need to be initialized in 
order to perform the SYS$WRITE operations. The %LOC function is used to create the 
address value required in the RBF field. One of the main reasons that block mode I/O is so 
efficient is that it avoids copy operations by using the data areas of the program directly for 
the output buffer. If the program specified, for a write to a disk device, a value for RSZ that 
was not an integral multiple of 512, the final block would be only partly filled. 
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OUTPUT 


C 

C 

C 

C 

C 


C 

C 


C 

c 


c 

c 


c 

c 


c 

c 


c 

c 

c 


Function to output records in b1ocK I/O mode 


OPTIONS /EXTEND-SOURCE 
LOGICAL FUNCTION OUTPUT(RAB) 

Declare RMS names 

INCLUDE 7 < $RABDEF) 7 
INCLUDE 7 ( $ S Y S S R U N A M ) 7 


Declare the RAB 


RECORD /RABDEF/ RAB 


Declare the Array to output 


REAL*8 A(6400) 

Declare the status variable 


INTEGER*^ STATUS 


Initialize the array 


DO 1=6400 *1 t-1 
A ( I ) = I 

ENDDO 

Now > output the array > two 512-byte (64 elements) 
blocks at a time 

OUTPUT = ♦ F ALSE♦ 

RAB♦RAB$M_RSZ = 1024 
DO I=0>99t2 


C For each block# set the buffer address to the 

C proper array element 

C 

RAB♦RAB$L_RBF = %LOC ( A ( I *64+1)) 

STATUS = SYS$WRITE(RAB) 

IF ( ♦NOT ♦ STATUS) RETURN 
ENDDO 

C Successful output completion 

C 

OUTPUT = ♦ TRUE♦ 

RETURN 

END 
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INPUT Routine 


This routine reads the array A from the file and verifies its values. The USZ and UBF fields 
of the RAB are the only fields that need to be initialized. The I/O transfer size is twice as 
large as the OUTPUT routine. The reason that this can be done is that the OUTPUT rou¬ 
tine writes, to a disk device, an integral number of 512-byte blocks. This method cannot be 
used if the writing routine either specifies an RSZ which is not a multiple of 512 or 
attempts to write to a magnetic tape device. 

c 

C INPUT 

C 

C Function to input records in b 1 o c K I/O mode 

C 

OPTIONS 
LOGICAL 

C Declare 

C 

INCLUDE 
INCLUDE 

C Declare 

C 

RECORD 

C Declare 

C 

REAL*8 A(6400) 

C Declare the status variable 

C 

INTEGER*^ STATUS 

C Now * read the array , four 512-b yt e (64 elements) 

C blocks at a time 

C 

INPUT = .FALSE♦ 

RAB♦RAB$N_USZ = 2048 
DO 1=0,98,4 

C For each block, set the buffer address to 

C the proper array element 

C 

RAB ♦ RAB$L_UBF = L 0 C ( A ( 1*64+1 ) ) 

STATUS = SYS$READ(RAB) 

IF (.NOT* STATUS) RETURN 
ENDDO 


/EXTEND-SOURCE 
FUNCTION INPUT(RAB) 

RMS names 

7 ($RABDEF) 7 
7 ( $ S Y S S R 0 N A M ) 7 

the RAB 

/RABDEF/ RAB 

the Array to output 
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C Successful input completion if data is correct 

C 

DO I=G400»1>-1 

IF (A( I ) ♦NE♦ I) RETURN 

ENDDO 

INPUT = * TRUE♦ 

RETURN 

END 
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Chapter 5 

Interprocess Communications 


This chapter contains information on how to exchange and share data among processes — 
both local (that is, involving a single VAX processor) and remote (that is, involving sepa¬ 
rate VAX processors that are interconnected by means of DECnet). 

5.1 Local Processes — Sharing and Exchanging Data 

Interprocess communication mechanisms provided for local processes allow: 

• Sharing programs (images) in shareable image libraries 

• Sharing data in installed common areas 

• Sharing data in files 

• Passing information by means of mailboxes 

• Passing information over DECnet-VAX network links 
These topics are discussed in this order in the sections that follow. 

5.1.1 Sharing Images in Shareable Image Libraries 

If you have a routine that is invoked by more than one program, you should consider estab¬ 
lishing it as a shareable image and installing it on your system. 

Establishing a routine as a shareable image provides the following benefits: 

• Saves disk space — The executable images to which the shareable image is linked do 
not actually include the shareable image. Only one copy of the shareable image 
exists. 

• Simplifies maintenance — If you use transfer vectors and the GSMATCH option, you 
can modify, recompile, and relink a shareable image without having to relink the exe¬ 
cutable images that reference it. 

Installing a shareable image as shared (INSTALL command, /SHARED qualifier) can also 
save memory. 


5-1 


The steps to creating and installing a shareable image are as follows: 

1. Compile the source file containing that routine that you want to establish as a 
shareable image. 

2. Link the shareable image object file that results from step 1, specifying any object 
files that contain routines referenced by the shareable image object file. 

The Linker utility provides a variety of options that you should consider before 
performing the link operation. See the VAX/VMS Linker Reference Manual for 
detailed information on shareable images and Linker options. 

3. Create a shareable image library using the Library utility’s LIBRARY command. 
See the VAX/VMS Utilities Reference Manual for detailed information on creating 
shareable image libraries. 

4. Install the shareable image (the results of step 3) on your system as a shared image 
(Install utility’s INSTALL command, /SHARED qualifier). For detailed informa¬ 
tion on how to perform this operation, see the VAX/VMS Install Utility Reference 
Manual. Also see the VAX/VMS System Management and Operations Guide for 
general information about installing known images. 

Any programs that access a shareable image must be linked with that image. When per¬ 
forming the link operation, you must specify one of the following items on your LINK 
command: 

1. The name of the shareable image library containing the symbol table of the share¬ 
able image — use the /LIBRARY qualifier to identify a library file. 

2. A linker options file that contains the name of the shareable image file — use the 
/SHAREABLE qualifier to identify a shareable image file. 

Note: A shareable image file must be specified in an options file because the Linker* 
creates a shareable image whenever it discovers a /SHAREABLE qualifier in the 
LINK command line. 

The resulting executable image contains the contents of each object module and a pointer 
to each shareable image. 

5.1.2 Sharing Data in Installed Common Areas 

Sharing the same data among two or more processes can be done using installed common 
areas. 

Typically, you use an installed common area for interprocess communication or for two or 
more processes to access the same data simultaneously. 
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To communicate between processes using a common area, first install the common area as 
a shareable image: 

1. Create the common area — Write a FORTRAN program that declares the variables 
in the common area and defines the common area. This program should not con¬ 
tain executable code. For example: 

COMMON /WORK_AREA/ WORK-ARRAY(8192) 

END 

2. Make it a shareable image — Compile the program containing the common area 
and use the LINK/SHAREABLE command to create a shareable image containing 
the common area. 

$ FORTRAN INC_COMMON 
$ LINK/SHAREABLE INC-COMMON 

3. Install the shareable image — Invoke the interactive Install utility. When the 
INSTALL> prompt appears, type CREATE, the complete file specification of the 
shareable image that contains the common area (file type defaults to EXE), and 
the qualifiers /WRITEABLE and /SHARED. (This operation requires CMKRNL 
privilege.) The Install utility installs your shareable image and reissues the 
INSTALL> prompt. Type EXIT to exit. 

$ INSTALL 
INSTALL > CREATE 

DISK*USER:[INCOME♦DEO]INC-COMMON/WRITEABLE/SHARED 
INSTALL> EXIT 

A disk containing an installed image cannot be dismounted until the installed 
image is deleted. To delete an installed image, invoke the Install utility and type 
DELETE followed by the complete file specification of the image. To exit from 
Install, use the EXIT subcommand. 

See the VAX/VMS Install Utility Reference Manual for additional information 
about the Install utility. 

When the common area has been installed, use the following steps to access the data from 
any program: 

1. Include the same variable definitions and common area definitions in the acces¬ 
sing program. 

2. Compile the program. 

3. Link the accessing program against the installed common area program. Use an 
options file to specify the common area program as a shareable image. 

LINK commands: 

$ LINK INCOME * INCOME/OPTION 
$ LINK REPORT * I NCOME/0PTI ON 

Specification in linker options file: 

I NC-COMMON/SHAREABLE 
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4. Execute the accessing program. 

In the previous series of examples, the two programs INCOME and REPORT access the 
same area of memory through the installed common area INCOME_DATA. 

5.1.2,1 Synchronizing Access - Typically, programs accessing shared data use common 
event flag clusters to synchronize read and write access to the data. In the simplest case, 
one event flag in a common event flag cluster might indicate that a program is writing data 
and a second event flag in the cluster might indicate that a program is reading data. Before 
accessing the shared data, a program must examine the common event flag cluster to 
ensure that accessing the data does not conflict with an operation already in progress. 

See the VAX/VMS System Services Reference Manual for detailed information about the 
use of event flags. 


5.1.3 Sharing Data in Files 

With the RMS file-sharing capability, you can allow file access by more than one program 
at a time or by the same program on more than one logical unit. 

There are two kinds of file sharing: read sharing and write sharing. 

• Read sharing occurs when multiple programs are reading a file at the same time. 

• Write sharing takes place when at least one program is writing a file and at least one 
other program is either reading or writing the same file. 

The extent to which file sharing can take place is determined by three factors: the type of 
device on which the file resides, the organization of the file, and the explicit information 
supplied by the user. Each of these concerns is discussed below: 

• Device type — Sharing is possible only on disk files. 

• File organization — All three file organizations — relative, indexed, and sequential — 
permit read sharing on disk files. In addition, relative and indexed files allow write 
sharing. 

Sequential files allow a restricted form of write sharing. This restriction is that only 
one program at a time can be writing to a sequential file. However, because the file 
system does not protect against simultaneous updating of sequential file records, your 
program must ensure that access conflicts cannot occur. 

• Explicit file-sharing information supplied by accessing programs — Whether file shar¬ 
ing actually takes place depends on information provided to VAX RMS by each pro¬ 
gram accessing the file. In FORTRAN programs, this information is supplied by the 
OPEN statement keywords, READONLY and SHARED. 

Read sharing is accomplished when READONLY is specified by all programs acces¬ 
sing the file. Write sharing is accomplished when the program specifies SHARED and 
not READONLY. 
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Programs that specify READONLY or SHARED can access a file simultaneously, 
with the exception that a file opened for READONLY cannot be accessed by a program 
that specifies SHARED. If READONLY or SHARED is not specified by both the pro¬ 
gram that initially opened a file and any other program that attempts to access that 
file, the latter program’s attempt to access the file will fail. That is, a program without 
a READONLY or SHARED keyword will fail in its attempt to open a file currently 
being accessed by some other program just as a program specifying READONLY or 
SHARED will fail to open a file if the program currently accessing that file did not 
specify READONLY or SHARED. 

When two or more programs are write sharing a file, each program should use one of the 
error-processing mechanisms described in Chapter 5. Use of one of these controls, the RMS 
record-locking facility, prevents program failure due to a record-locking error. 

The RMS record-locking facility, along with the logic of the program, prevents two 
processes from accessing the same record at the same time. Record locking ensures that a 
program can add, delete, or update a record without having to check whether the same 
record is simultaneously being accessed by another process. 

When a program opens a relative or indexed file specifying SHARED, RMS locks each 
record as it is accessed. When a record is locked, any program attempting to access it fails 
with a record locked error. A subsequent I/O operation on the logical unit unlocks the pre¬ 
viously accessed record. Thus, no more than one record on a logical unit is ever locked. 

Locked records can be explicitly unlocked by means of FORTRAN’S UNLOCK statement. 
The use of this statement minimizes the amount of time that a record is locked against 
access by other programs. The UNLOCK statement should be used in programs that 
retrieve records from a shared file but do not attempt to update them. See the Program¬ 
ming in VAX FORTRAN for additional information about the UNLOCK statement and 
its syntax. 

Record locking is not provided for sequential files. These files can be write shared, how¬ 
ever, as long as you provide the logic necessary to handle the simultaneous reading and 
writing. 

For additional information about record locking for shared files, see the VAX Record Man¬ 
agement Services Reference Manual. 

Section 15.7 in the Programming in VAX FORTRAN describes how to handle record lock¬ 
ing for indexed files. 

5.1.4 Using Mailboxes to Pass Information 

It is often useful to exchange data between processes: for example, to synchronize execu¬ 
tion or to send messages. 

A mailbox is a record-oriented pseudo I/O device that allows you to pass data from one 
process to another. Mailboxes are created by the Create Mailbox system service 
(SYS$CREMBX). The following sections describe how to create mailboxes and how to send 
and receive data using mailboxes. 
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5.1.4.1 Creating a Mailbox - SYS$CREMBX creates the mailbox and returns the number 
of the I/O channel assigned to the mailbox. You must specify a variable for the I/O channel. 
You should also specify a logical name to be associated with the mailbox. The logical name 
identifies the mailbox for other processes and for FORTRAN I/O statements. The 
SYS$CREMBX system service also allows you to specify the message and buffer sizes, the 
mailbox protection code, and the access mode of the mailbox; however, the default values 
for these arguments are usually sufficient. 

The following segment of code creates a mailbox named MAILBOX. The number of the I/O 
channel assigned to the mailbox is returned in ICHAN. 

INCLUDE 7 <$SYSSRUNAM) 7 
INTEGER*2 ICHAN 

ISTATUS = S Y S $ C R E M B X ( »I C H A N t t t * * 'MAILBOX 7 ) 

For more information about calling system services, see Chapter 6. For more information 
about the arguments supplied to the Create Mailbox system service, see the VAX/VMS 
System Services Reference Manual. 


NOTE 

Do not use MAIL as the logical name for a mailbox. If you do so, the system will 
not execute the proper image in response to the DCL command MAIL. 


5.1.5 Sending and Receiving Data Using Mailboxes 

Sending data to and receiving data from a mailbox is no different from other forms of 
FORTRAN I/O. The mailbox is simply treated as a record-oriented I/O device. 

Use FORTRAN formatted sequential READ and WRITE statements to send and receive 
messages. The data transmission is performed synchronously. That is, a program that 
writes a message to a mailbox waits until the message is read, and a program that reads a 
message from a mailbox waits until the message is written before it continues transmis¬ 
sion. When the writing program closes the mailbox, an end-of-file condition is returned to 
the reading program. 

Do not attempt to write a record of zero length to a mailbox; the program reading the 
mailbox interprets this record as an end-of-file. Zero-length records are produced by con¬ 
secutive slashes in FORMAT statements. 

The sample program below creates a mailbox assigned with the logical name MAILBOX. 
The program then performs an open operation specifying the logical name MAILBOX as 
the file to be opened. It then reads file names from FNAMES.DAT and writes them to the 
mailbox until all of the records in the file have been transmitted. 
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CHARACTER FILENAME*G4 
INCLUDE 7 ($SYSSRUNAM) 7 
INTEGER*2 ICHAN 
INTEGER*4 STATUS 


STATUS = S Y S $ C R E M B X ( * I C H A N » » * * »'MAILBOX 7 ) 

IF ( ♦ NOT♦ STATUS) GO TO SS 

OPEN (UN IT = S * FILE="MAILBOX 7 * 

1 STATUS = 7 NEN 7 * CARRIAGECONTROL= 7 LI ST 7 * ERR = 99> 

OPEN (UN I T = 8 * FILE= 7 FNAMES*DAT" * STATUS= 7 OLD 7 ) 


10 READ (8 #100* E N D = 9 8 ) FILENAME 
WRITE (9 »100) FILENAME 


100 FORMAT(A) 
GO TO 10 


98 CLOSE (UN IT = 8) 

CLOSE (UN IT = 9) 

STOP 

99 WRITE ( G * * ) "Mailbox error" 
STOP 

END 


The sample program below reads messages from a mailbox which was assigned the logical 
name MAILBOX when it was created. The messages comprise file names, which the pro¬ 
gram reads. The program then types the files associated with the file names. 

CHARACTER FILNAM*G4 * TEXT*133 



OPEN 

( UN IT = 1 » 

F I LE = 

"MAILBOX 7 * STATUS= "OLD 7 ) 

1 

READ 

( 1 ,100 >END= 1 2) 

FILNAM 

1 00 

FORMAT (A) 




OPEN 

(UN IT = 2t 

F I LE = 

FILNAM* STATUS= "OLD 7 ) 


OPEN 

( UN IT = 3» 

F I LE = 

"SYS$OUTPUT 7 * STATUS = "NEW 

*-> 

READ 

(2 » 100 »END =1 0 ) 

TEXT 


WRITE 

(3*1 00 ) 

TEXT 



GO TO 

'P 



10 

CLOSE 

(UN IT = 2 

) 



CLOSE (UN IT = 3) 
GO TO 1 


12 END 
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5.2 Remote Processes — Sharing and Exchanging Data 

If your computer is a node in a DECnet-VAX network, you can communicate with other 
nodes in the network by means of standard FORTRAN I/O statements. These statements 
let you exchange data with a program at the remote computer (task-to-task communica¬ 
tion) and access files at the remote computer (resource sharing). There is no apparent dif¬ 
ference between these intersystem exchanges and the local interprocess and file access 
exchanges. 

Remote file access and task-to-task communications are discussed separately in the sec¬ 
tions that follow. 

5.2.1 Remote File Access 

To access a file on a remote system, include the remote node name in the file name specifi¬ 
cation. For example: 

BOSTON: :DBA0:[SMITH]TEST♦DAT 5 2 

See Programming in VAX FORTRAN for additional information about file specifications. 

To make a program independent of the physical location of the file(s) it accesses, you can 
assign a logical name to the network file specification as shown in tb^ Allowing example: 

$ ASSIGN MIAMI::DR4:CIN03INMENT.DAT INVFILE 

The logical name INVFILE now refers to the remote file and can be used in the program. 
For example: 

OPEN (UNIT =10 t FILE= ' INYFILE 7 > STATUS = "OLD') 

To process a file on the local network node, reassign the logical name; you do not need to 
modify the source program. 

5.2.2 Network Task-to-Task Communication 

Network task-to-task communication allows a program running on one network node to 
interact with a program running on another network node. This interaction is accom¬ 
plished with normal FORTRAN I/O statements and looks much like an interactive pro¬ 
gram/user session. 

The steps involved in network task-to-task communications are as follows: 

1. Request the network connection 

The originating program initiates task-to-task communication. It opens the 
remote task file with a special file name syntax: the name of the remote task file is 
preceded with TASK = and surrounded with quotation marks. For example: 

BOSTON:: M TASK=UPDATE" 
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Unless the remote task file is contained in the default directory for the remote 
node’s DECnet account, you must specify the pertinent account information (a 
user name and password) as part of the node name: 

B 0 S T 0 N " u s e rname p a s s w o rd": :"TASK = UPDATE" 

The form of the remote task file varies, depending on the remote computer’s operat¬ 
ing system. For VAX/VMS systems, this task file is a command file with a file type 
of COM. The network software submits the command file as a batch job on the 
remote system. 

2. Complete the network connection 

When the remote task starts, it must complete the connection back to the host. On 
VAX/VMS, the remote task completes this connection by performing an open oper¬ 
ation on the logical name SYS$NET. When opening the remote task file or 
SYS$NET, you should specify either FORM = 'UNFORMATTED' or the combina¬ 
tion of FORM = 'FORMATTED' and C ARRIAGECONTROL = 'NONE'. 

3. Exchange messages 

When the connection is made between the two tasks, each program performs I/O 
using the established link. 

Task-to-task communication is synchronous. This means that when one task per¬ 
forms a read, it waits until the other task performs a write before it continues 
processing. 

4. Terminate the network connection 

To prevent losing data, the program that receives the last message should termi¬ 
nate the network connection using the CLOSE statement. When the network con¬ 
nection is terminated, the cooperating image receives an end-of-file error. 

The following is a complete example showing how FORTRAN programs can exchange 
information over a network. In this example, the originating program prompts for an inte¬ 
ger value and sends the value to the remote program. The remote program then adds one to 
the value and returns the value to the originating program. It is assumed that the remote 
operating system is VAX/VMS. 

The originating program on the local node is: 

OPEN (UNIT=10 » F I L E = "PARIS: :" TASK = REMOTE" 7 t 

1 STATUS = 'OLD" * FORM =/ UNFORMATTED ' » 

2 ACCESS =/ SEQUENT IAL ' * IOSTAT=IOS> ERR=9309) 

C Prompt for a numbe r 
PRINT 101 

101 FORMAT <$»' ENTER A NUMBER: ') 

ACCEPT *»N 
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C Perform the network I/O 


WRITE (UN IT=10 * IOSTAT=IOS * ERR=9999) N 
READ < UNIT=10 * IOSTAT=IOS t ERR = 9999) N 


C Output the number and process errors 


PRINT 102 * N 

102 FORMAT ( " The new value is ' till) 


GO TO 99999 

9999 PRINT * t "Unexpected I/O Error Number " » IOS 
99999 CLOSE (UNIT=10) 


END 


The task file REMOTE.COM on the remote node is: 


$ DEFINE SYS$PRINT NL: 

$ RUN DBG:[NET]REMOTE♦EXE 
$ PURGE/KEEP=2 REMOTE.LOG 


Inhibit printing of 1 o S 
Run remote program 
Delete old loS files 


The source of the remote program PARIS::DBO:[NET]REMOTE.EXE is: 


OPEN (U NIT =10 * FILE="SYS$NET" * FORM='UNFORMATTED 
1 ACCESS = "SEQUENTIAL" t STATUS="OLD") 


READ (U NIT =10) N 
N = N + 1 
WRITE (UN IT=10) N 
CLOSE (U NIT =10) 

END 

For more information on using DECnet, refer to the DECnet-VAX Users Guide, DECnet- 
VAX System Managers Guide, and Introduction to DECnet. 
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Chapter 6 

VAX Condition Handling Facility 


Exception conditions are events, usually errors, that occur during the execution of a 
program. 

An exception condition can be related to either a hardware or software event. 

• Hardware exceptions include floating overflows, memory access violations, and the 
use of reserved operands. 

• Software exceptions include output conversion errors, end-of-file conditions, and 
invalid arguments to mathematical procedures. 

An exception condition handler is a procedure that is invoked when an exception condition 
occurs. 

You can create and establish your own condition handlers to accommodate the needs of 
your applications. For example, you can create and display messages that specifically 
describe conditions encountered during execution of an application program, instead of 
relying on the system’s standard error messages. 

For additional information about the Condition Handling Facility, se Appendix C of the 
VAX-11 Architecture Reference Manual , Chapter 6 of the VAX/VMS RTL Users Guide , 
and Appendix C of the VAX/VMS Run-Time Library Reference Manual. 


6.1 Overview of the VAX Condition Handling Facility 

The VAX Condition Handling Facility (CHF) coordinates processing for all exception con¬ 
ditions that occur during execution of a FORTRAN program. When an exceptional event 
occurs, the Condition Handling Facility is activated. It takes program control away from 
the routine that is currently executing and begins searching for a handler procedure to 
call. If it finds one, it establishes a stack frame and calls the handler procedure. The han¬ 
dler procedure then attempts to deal with the event. The following sections describe the 
process in more detail and explain the possible actions that a handler can take. 

You should be familiar with the following terms in order to fully understand the material 
in this chapter. These terms are discussed in detail in the VAX/VMS Run-Time Library 
User's Guide. 
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• Exception condition — a hardware-generated synchronous exception or a software 
event that changes the normal flow of instruction execution. 

• Condition symbol — a symbol used to specify a condition value; it has the form: 

fac$_symbol (DIGITAL-defined) 
or 

fac$_symbol (user-defined) 
where: 

fac 

is a facility name prefix. 

symbol 

identifies a specific condition. 

Refer to Table 18-1 of Programming in VAX FORTRAN for a list of FORTRAN- 
related condition symbols. 

• Procedure — an executable program unit; a main program, subroutine, or function. 

• Procedure activation — the environment in which a procedure executes. This environ¬ 
ment includes a unique stack frame on the run-time stack; the stack frame contains 
the address of a condition handler for the procedure activation. A new procedure acti¬ 
vation is created every time a procedure is called; the procedure activation is deleted 
when the procedure returns. 

• Condition handler — a function that a procedure activation specifies as the procedure 
to be called when an exception condition occurs. 

• Establish — the process of placing the address of a condition handler in the stack 
frame for the current procedure activation. A condition handler established for a pro¬ 
cedure is automatically called when an exception condition occurs. In FORTRAN, 
condition handlers are established by means of the LIB$ESTABLISH procedure. See 
Section 6.5. 

• Signal — the process of taking control away from the executing program and initiat¬ 
ing the operation of the Condition Handling Facility. Signals are generated by the 
VAX/VMS operating system in response to hardware exceptions. Signals are also ini¬ 
tiated by a call to a signal procedure, which in turn calls a condition handler. There 
are two signal procedures: 

- LIB$SIGNAL — used to signal a condition and possibly continue program 
execution. 

— LIB$STOP — used to signal a severe error and discontinue program execution, 
unless a condition handler performs an unwind. 

See Section 6.3. 
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• Resignal — the means by which a condition handler indicates that the signal proce¬ 
dure is to continue searching for a condition handler to process a previously signaled 
error. To resignal, a condition handler returns the SS$_RESIGNAL value. See 
Section 6.7. 

• Unwind — the act of returning control to a particular procedure activation, bypassing 
any intermediate procedure activations. For example, if X calls Y, and Y calls Z, and Z 
detects an error, then a condition handler associated with Z can unwind to X, bypass¬ 
ing Y. Control returns to X immediately following the point at which X called Y. 


6.2 Default Condition Handler 

When the VAX/VMS system creates a user process, it establishes a system-defined condi¬ 
tion handler that will, in the absence of any user-established condition handler, process 
errors that occur during execution of the user image. 

This default condition handler is the last one reached when a search is undertaken to find a 
condition handler to respond to an error. If no lower-level procedure has established a han¬ 
dler, or if all lower-level handlers have resignaled, the default condition handler responds. 
The default handler calls the system’s message output routine to send the appropriate 
message to the user. Messages are sent to the SYS$OUTPUT file and to the SYS$ERROR 
file if these files are both present. If the condition is one that permits continuation, pro¬ 
gram execution continues at the point the exception occurred. Otherwise, the default han¬ 
dler forces program termination, and the condition value (see Table 18-1 of Programming 
in VAX FORTRAN) becomes the program exit status. 

6.3 Condition Signals 

When you want to initiate the operation of the Condition Handling Facility (CHF) from 
your program, you have your program issue a condition signal. A condition signal consists 
of a call to one of the two system-supplied signal procedures in either of the following 
forms: 

CALL LIB$SIGNAL(condition-value, arg, ..., arg) 

CALL LIB$STOP(condition-value, arg, ..., arg) 
where: 

condition-value 

is an INTEGER*4 value that identifies a particular exception condition. See Appen¬ 
dix C, Section C.4, of the VAX/VMS Run-Time Library Reference Manual. 
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arg 

optional arguments to be passed to user-established condition handlers and the sys¬ 
tem default condition handlers. These arguments consist of messages and formatted- 
ASCII-output arguments (see the VAX/VMS Run-Time Library Reference Manual). 

The CHF uses these parameters to build the signal argument array SIGARGS before pass¬ 
ing control to a condition handler. 

You can use a condition signal when you do not want to handle a condition in the routine in 
which it was detected, but wish instead to pass the information to a higher-level routine. 

If the current procedure can continue after the signal is made, call LIB$SIGNAL. A 
higher-level procedure can then determine whether program execution continues. If the 
condition does not allow the current procedure to continue, call LIB$STOP. 

To pass the condition value, you must use the %VAL argument list built-in function (see 
Section 3.1.3.1). Condition values are usually expressed as condition symbols (see Section 
3.3.1). For example: 

CALL LIB$SIGNAL(7,0AL(MTH$_FL000ENAT) ) 

You can include additional arguments to provide supplementary information about the 
error. 

When your program issues a condition signal, the CHF searches for a condition handler by 
examining the preceding stack frames in order, until it either finds a procedure that han¬ 
dles the condition or reaches the default condition handler. 

6.4 Handler Responses 

A condition handler responds to an exception by taking action in three major areas: 

(1) condition correction, (2) condition reporting, and (3) execution control. 

First, the handler should determine whether it can correct the condition. If possible, the 
handler takes the appropriate corrective action and execution continues. If it cannot cor¬ 
rect the condition, the handler may resignal the condition. That is, it may request that 
another condition handler process the exception. 

Condition reporting performed by handlers can involve one or more of the following 
actions: 

• Maintaining a count of exceptions encountered during program execution 

• Resignaling the same condition to send the appropriate message to your terminal or 
log file 

• Changing the severity field of the condition value and resignaling the condition 

• Signaling a different condition, for example, to produce a message appropriate to a 
specific application 
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Execution can be affected in a number of ways, such as: 

• Continuing from the point of exception. However, if the signal was issued by means of 
a call to LIB$STOP, the program exits. 

• Unwinding to the establisher at the point of the call that resulted in the exception. 
The handler specifies the function value to be returned by the called procedure. 

• Unwinding to the established caller (the procedure that called the procedure that 
established the handler). The handler specifies the function value to be returned by 
the establisher. 

See Section 6.7 for information about returning from condition handlers. 

6.5 Establishing and Removing Condition Handlers 

A condition handler is not automatically established when your program calls a proce¬ 
dure. If you want to use a condition handler, you must establish it by calling the Run-Time 
Library procedure LIB$ESTABLISH, including code similar to the following in the call: 

EXTERNAL HANDLER 

CALL LIB$ESTABLISH(HANDLER) 

In the preceding example, HANDLER is the name of a FORTRAN function subprogram 
that is established as the condition handler whenever that procedure is called. When the 
procedure returns, the condition handler is automatically removed. To remove an estab¬ 
lished handler before returning, call the Run-Time Library procedure LIB$REVERT, as 
follows: 

CALL LIB$REOERT 

This call removes the condition handler established in the current procedure. 


6.6 FORTRAN Condition Handlers 

A FORTRAN condition handler is an INTEGER*4 function that is called when an excep¬ 
tion condition occurs. You must define two dummy arguments for a condition handler: 

1. An integer array to refer to the argument list associated with the call to invoke the 
CHF (the “signal arguments”), that is, the list of arguments included in CALL 
LIB$SIGNAL or CALL LIB$STOP (see Section 6.3) 

2. An integer array to refer to information concerning the procedure activation that 
established the condition handler (the “mechanism arguments”) 

For example, you could define a condition handler as follows: 

INTEGER*^ FUNCTION HANDLER(SIGARGS»MECHARGS) 

INTEGER*^ SIGARGS(*) » MECHARGS(B) 
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Before invoking a condition handler, the CHF creates the signal and mechanism argument 
arrays SIGARGS and MECHARGS. 


The array SIGARGS is used to obtain information from the signal procedure. The values 
from the signal procedure are shown below: 


Array Element Contents 


SIGARGS(l) 
SIGARGS(2) 
SIGARGS(3 to n-1) 


SIGARGS(n) 
SIGARGS(n + 1) 


Condition 

Zero or more 
additional 
arguments 

PC 

PSL 


> n 


Where n represents the argument count, that is, the number of elements in SIGARGS, not 
including the first element. 


Notes: 

• The first element of the array, SIGARGS(l), indicates how many additional argu¬ 
ments are being passed in this vector (argument count). The count does not include 
this first element. 


The second element, SIGARGS(2), indicates the signaled condition (condition value). 
See Section 6.8 for a discussion of condition values. 


• There may be additional arguments, SIGARGS(3) to SIGARGS (n—1), specified in the 
call to LIB$SIGNAL or LIB$STOP. 


• The second-to-last element, SIGARGS(n), indicates the program counter (PC) at the 
point where the exception occurred. 


• The last element, SIGARGS( + 1), indicates the processor status longword (PSL) at 
the point where the exception occurred. 


The array MECHARGS is used to obtain information about the procedure activation of the 
procedure that established the condition handler. MECHARGS is a 5-element array; its 
values are defined below: 


Array Element 

Contents 

MECHARGS* 1) 

4 

MECHARGS(2) 

frame-ptr 

MECHARGS(3) 

call-depth 

MECHARGS(4) 

RO-value 

MECHARGS(5) 

Rl-value 
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Notes: 

• The first element, MECHARGS(l), is the argument count of this vector (4). 

• MECHARGS(2) contains the address of the procedure activation stack frame that 
established the handler (frame pointer). 

• MECHARGS(3) contains the number of calls (depth) made from the procedure activa¬ 
tion, up to the point at which the exception occurred. 

• MECHARGS(4) and MECHARGS(5) contain the values of registers RO and R1 at the 
time of the signal. When execution continues or when a stack unwind occurs, these 
values are restored to RO and Rl. Therefore, a handler can change the function value 
returned to a caller by modifying these register values and performing an unwind. 

Inside a condition handler, you can use any other variables that you want. If they are 
shared with other program units (for example, in COMMON), make sure they are declared 
volatile. This will ensure that compiler optimizations will not invalidate the handler 
actions. See Section 1.3.2.2 or Chapter 8 in the VAX FORTRAN Users Guide for more 
information on the VOLATILE statement. 


6.7 Returning from a Condition Handler 

One way that condition handlers control subsequent execution is by specifying a function 
return value. Function return values and their effects are defined in Table 6-1. 

Table 6-1: Condition Handler Function Return Values 


Symbolic Values Effects 

SS$_CONTINUE Continue execution from the signal. If the signal was issued by a call to 
LIB$STOP, however, the program exits. 

SS$_RESIGNAL Resignal to continue the search for a condition handler to process the con¬ 
dition. 

Alternatively, a condition handler can request a stack unwind by calling SYS$UNWIND 
before returning. In this case, handler function return values are ignored. 

If the procedure being unwound is a function whose value is returned in RO or in RO and 
Rl, then the handler can modify the function value that is returned to its caller by chang¬ 
ing the saved values of RO and Rl in the mechanism argument list (MECHARGS(4) and 
MECHARGS(5)). 

A stack unwind is typically made to one of two places: 

• To the establishes Specify: 

CALL SYS$UNWIND(MECHARGS(3) ») 

Control returns to the establisher following the call that resulted in the exception. 
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• To the establisher’s caller. Specify: 

CALL SYS$UNMIND( ») 

Control returns to the caller of the establishes 

The actual stack unwind occurs when a condition handler returns control to the condition 
handling facility. For more information on requests to unwind, refer to the VAX-11 Archi¬ 
tecture Reference Manual and to the VAX/VMS Run-Time Library Users Guide. 


6.8 Condition Values and Symbols 

The VAX system uses condition values to indicate that a called procedure has either exe¬ 
cuted successfully or failed, and to report exception conditions. Condition values are 
INTEGER*4 values. They consist of fields that indicate which system component gener¬ 
ated the value, the reason the value was generated, and the severity of the condition. A 
condition value has the form: 


31 28 27 16 15 3 2 0 


c 

FACILITY 

MESSAGE 

SEV 


ZK-795-82 


C field (31:28) — control bits. 

Facility (27:16) — identifies the software component that generated the condi¬ 

tion value. Bit 27 = 1 indicates a customer facility. Bit 27 = 0 
indicates a DIGITAL facility. 

Message (15:3) — describes the condition that occurred. Bit 15 = 1 indicates 

that the message is specific to a single facility. Bit 15 = 0 indi¬ 
cates a system-wide message. 

Sev (2:0) — severity code, as follows: 

0 — warning 

1 — success 

2 — error 

3 — information 

4 — severe error 
5, 6, 7 —reserved 

The warning and error codes have the following meanings: 

• A warning severity code (0) indicates that output was produced but that the results 
might not be what you expected. 
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• An error severity code (2) indicates that output was produced even though an error 
was detected. Execution can continue, but the results may not all be correct. 

• A severe error code (4) indicates that the error was of such severity that output was 
not produced. 

One of the functions that can be performed by a condition handler is the altering of the 
severity code of a condition value to allow execution to continue or to force an exit, depend¬ 
ing on the circumstances. 

The condition value is passed as the second element of the array SIGARGS. There are 
times when you may require that a particular condition be identified by an exact match. 
That is, each bit of the condition value (31:0) must match the specified condition. For 
example, you may want to process a floating overflow condition only if its severity code is 
still 4 (in other words, if no previous handler has changed the severity code). As noted pre¬ 
viously, a typical handler response is to change the severity code and resignal. 

In many cases, however, you may want to respond to a condition regardless of the value of 
the severity code. To ignore the severity and control fields of a condition value, use the 
LIB$MATCH_COND function, in the form: 

index = LIB$MATCH_COND(SIGARGS(2),con-1,con-2,...con-n) 

where: 

con 


is a condition value. 

The LIB$MATCH_COND function compares bits 27:3 of the value in SIGARGS(2) with 
bits 27:3 of each specified condition value. If it finds a match, the function assigns the index 
value according to the position of the matching condition value in the list. That is, if the 
match is with the third condition value following SIGARGS(2), then index = 3. If no 
match is found, index = 0. The value of the index can then be used to transfer control, as in 
the following example: 

INTEGER*# FUNCTION HANDL<SIGARGS>MECHARGS) 

INCLUDE ' ($F0RDEF) ' 

INTEGER*# SIGARGS(*) * MECHARGS(5) 

INDEX=LIB$MATCH_COND(SIGARGS(2) »F0R$_FILNOTFOU» 

1 F0R$_N0_SUCDEU »F0R$_FILNAMS PE ,F0R$_0PEFAI ) 

GO TO (100*200 * 300 t #00) t INDEX 

HANDL=SS$_RESIGNAL 

RETURN 
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If no match is found between the condition value in SIGARGS(2) and any of the values in 
the list, then index = 0, and control transfers to the next executable statement after the 
computed GO TO. A match with any of the values in the list transfers control to the corre¬ 
sponding statement in the GO TO list. Thus, if SIGARGS(2) matches FOR$_OPEFAI, con¬ 
trol transfers to statement 400. Note the use of condition symbols to represent condition 
values. Refer to Table 18-1 of Programming in VAX FORTRAN for a list of the FORTRAN 
condition symbols and their meanings. 

The FORTRAN Symbolic Definition Library FORSYSDEF contains modules that define 
condition symbols. When you write a condition handler, you can specify the following mod¬ 
ules, as appropriate, with an INCLUDE statement: 

$FORDEF 

This module contains definitions for all condition symbols from the FORTRAN- 
specific Run-Time Library. Refer to Table 18-1 of Programming in VAX FORTRAN 
for a listing of the FORTRAN error numbers (IOSTAT values) associated with these 
symbols. These symbols have the form: 

FOR$_error 
For example: 

F0R$_INPC0NERR 

$LIBDEF 

This module contains definitions for all condition symbols from the VAX general util¬ 
ity library facility. These symbols have the form: 

LIB$_condition 
For example: 

LIB$_INSMIRMEM 

$MTHDEF 

This module contains definitions for all condition symbols from the mathematical 
procedures library. These symbols have the form: 

MTH$_condition 
For example: 

MTH$_SQUR00NEG 

$SSDEF 

This module contains system status codes, which are frequently used in FORTRAN 
condition handlers. These symbols have the form: 

SS$_status 
For example: 

SS$_FLTOOF 
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6.9 Faults and Traps 


You can have your program signal a condition by calling LIB$SIGNAL or LIB$STOP 
directly, as described in Section 6.3. However, most conditions are signaled on behalf of 
your program by the system hardware or software in response to a system event. These 
conditions are processed by the CHF and handled in the same way as described above. The 
following sections describe some of the system events that signal conditions on behalf of 
your program. 


If a VAX processor detects an error while executing a machine instruction, it can take one 
of two actions. 


• The first action, called a fault, preserves the contents of registers and memory in a 
consistent state so that the instruction can be restarted. 

• The second action, called a trap, completes the instruction, but with a predefined 
result. For example, if an integer overflow trap occurs, the result is the correct low- 
order part of the true value. 

The action taken when an exception occurs depends upon the type of exception. For exam¬ 
ple, faults are taken for access violations and for detection of a floating reserved operand. 
Traps are taken for integer overflow and for integer divide-by-zero exceptions. However, 
when a floating overflow, floating underflow, or floating divide-by-zero exception occurs, 
the action taken depends upon which type of VAX processor is executing the instruction. 





Early versions of the VAX-11/780 processor trap when these errors occur. For floating 
overflow or divide-by-zero, a floating reserved operand is stored in the destination; for 
floating underflow, a zero is stored in the destination. (Note: Most of these processors 
have been updated and now assume the error-handling behaviors of newer 
processors.) 


• All other VAX processors fault on these exceptions, allowing the error to be corrected 
and the instruction restarted. 

If a program that expects floating traps runs on a VAX processor that faults, execution may 
continue incorrectly. For example, if a condition handler merely causes execution to con¬ 
tinue after a floating trap, a reserved operand is stored and the next instruction is exe¬ 
cuted. However, the same handler used on a processor that faults causes an infinite loop of 
faults because it restarts the erroneous instruction. Therefore, you should write floating¬ 
point exception handlers that take the appropriate actions for both faults and traps. 


Separate sets of condition values are signaled by the processor for faults and traps. Excep¬ 
tions and their condition code names are: 


Exception 

Floating overflow 
Floating underflow 
Floating divide-by-zero 



Fault 

SS$_FLTOVF_F 

SS$_FLTUND_F 

SS$_FLTDIV_F 


Trap 

SS$_FLTOVF 

SS$_FLTUND 

SS$_FLTDIV 
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To convert faults to traps, you can use the Run-Time Library LIB$SIM_TRAP procedure 
either as a condition handler or as a called routine from a user-written handler. When 
LIB$SIM_TRAP recognizes a floating fault, it simulates the instruction completion as if a 
floating trap had occurred. For information on how to use this procedure, refer to the 
VAX/VMS Run-Time Library Reference Manual. 

Note that the PDP-11 FORTRAN compatibility error-processing routines ERRSET and 
ERRTST implicitly enable LIB$SIM_TRAP so that faults are converted to traps. 


6.10 Floating Reserved Operand Faults 

Certain errors resulting from floating-point operations generate special values, called 
floating reserved operands. Errors that occur in math library procedures and the floating 
overflow or division-by-zero traps are primary examples of conditions that produce float¬ 
ing reserved operands. 

A floating reserved operand has a sign bit of 1 and an exponent of 0. A floating reserved 
operand fault occurs when a VAX floating-point instruction retrieves a floating reserved 
operand. To continue program execution after this fault, you must provide a condition han¬ 
dler that changes the reserved operand to a nonreserved value and restarts the instruc¬ 
tion. As with other faults, if you restart the instruction without first correcting the 
condition, you create an infinite loop of faults. 

You can use the Run-Time Library procedure LIB$FIXUP_FLT to replace a reserved oper¬ 
and with a new value and restart the instruction. This procedure is either enabled as a 
condition handler or called from a user-written condition handler. 

You can enable the LIB$FIXUP_FLT procedure as a condition handler, as follows: 

EXTERNAL L I B$FIXUP_FLT 

CALL L I B$ESTABLISH(LIB$FI XUP_FLT) 

By default, the procedure replaces the reserved operand with a zero value and continues 
program execution. 

You can call LIB$FIXUP_FLT from a user-written condition handler, as shown in the fol¬ 
lowing example: 

INTEGER*4 FUNCTION HANDLER(SIGARGSt MECHARGS) 

INTEGER*^ SIGARGS (*) t MECHARGS(5) 

HANDLER = LIB$FIXUP_FLT(SIGARGS * MECHARGS * 1.0E0) 

RETURN 

END 

This condition handler returns the success or failure status value returned by 
LIB$FIXUP_FLT. If the correction is successful, execution continues; if not, the condition 
is resignaled. The third argument to LIB$FIXUP_FLT is optional and explicitly specifies 
the reserved operand replacement value; it must be a REAL*4 value. If you omit this argu¬ 
ment, however, LIB$FIXUP_FLT automatically supplies a value of zero. 
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For more information about the LIB$FIXUP_FLT procedure, refer to the VAX/VMS Run¬ 
Time Library Reference Manual. 

6.11 Floating Underflow 

FORTRAN, by default, does not enable underflow exceptions. If the result of an operation 
is smaller than the smallest representable floating-point number, the result is set to zero, 
program execution continues, and no error message is given. 

FORTRAN does, however, provide the facilities for reporting and processing underflow 
exceptions. You can enable underflow exceptions for all or part of a routine, and you can 
choose either FORTRAN default processing or provide a user-written handler. These 
options are discussed in the following sections. 

6.11.1 Specifying /CHECK = UNDERFLOW 

When you specify the /CHECK = UNDERFLOW qualifier in the FORTRAN command or 
OPTIONS statement, the compiler takes two actions: 

• Generates code to enable underflow at the beginning of each routine 

• For main programs, causes the FORTRAN-specific handler 
FOR$UNDERFLOW_HANDLER to become established in a frame above the main 
program at run time 

If an operation in the main program or subprogram underflows and it is not processed by 
another handler, FOR$UNDERFLOW_HANDLER assumes control and performs the fol¬ 
lowing actions: 

1. Increments a count of the number of underflows 

2. Changes an underflow fault to an underflow trap 

3. Prints an error message and generates a traceback for the first two underflows 

4. Stores a zero in the result 

5. Continues program execution 

When the program exits, an informational message is printed, giving the total number of 
underflows generated by the program. 

If the main program is not compiled with the /CHECK = UNDERFLOW qualifier, or if it is 
not in FORTRAN, a system default handler, not FOR$UNDERFLOW_HANDLER, 
assumes control when an underflow exception occurs. It prints a traceback listing and ter¬ 
minates the program execution. 
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6.11.2 User-Established Handlers for Underflow 


If you wish to handle underflow in a manner different from 
FOR$UNDERFLOW_HANDLER, you can establish a user handler (see Section 6.9). The 
user-established handler assumes control before the default handler, since the default 
handler is established in a frame above the main program. The user program thus has 
complete control over how the exception is processed. 

Note that when you write a handler for floating underflow, you must be careful to account 
for both faults and traps (refer to Section 6.9). 

If you desire the behavior of FOR$UNDERFLOW_HANDLER for underflow exceptions, 
but it is not possible to compile the main program with the /CHECK = UNDERFLOW 
qualifier, or the main program is not in FORTRAN, you can establish 
FOR$UNDERFLOW_HANDLER explicitly in any FORTRAN routine: 

EXTERNAL FOR$UNDERFLON_HANDLER 

CALL L I B$ESTABLISH(FOR$UNDERFLOW_HANDLER) 

Any combination of routines in a program can establish FOR$UNDERFLOW_HANDLER 
without interfering with the proper behavior of the handler. However, make sure that you 
establish the handler before the occurrence of any operations that could cause underflow. 

6.11.3 Enabling and Disabling Underflow 

You can enable or disable underflow exceptions for parts of a routine by using the Run¬ 
Time Library routine LIB$FLT_UNDER. The LIB$FLT_UNDER takes one argument: to 
enable underflow in the current routine, specify 1; to disable underflow in the current rou¬ 
tine, specify 0. 

For more information about LIB$FLT_UNDER, see the VAX/VMS Run-Time Library 
Reference Manual. 

6.12 Decoding Faults 

The Run-Time Library provides a procedure that allows you to override the default actions 
of the faults described in Section 6.11 or any other fault exceptions. The Run-Time proce¬ 
dure LIB$DECODE_FAULT decodes the operation that caused the exception and then 
allows a user-supplied routine to control the program action. For more information on 
LIB$DECODE_FAULT, refer to the VAX/VMS Run-Time Library Reference Manual. 


6.13 Condition Handler Examples 

The examples in this section illustrate condition handlers that apply to typical FORTRAN 
procedures. 
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Example 1: 

The following example uses a matrix inversion procedure, with the logical function name 
INVERT, to indicate the success or failure of the procedure. That is, if the matrix can be 
inverted, INVERT returns the .TRUE, logical value. If the matrix is singular, INVERT 
returns the .FALSE, logical value. During execution of the matrix inversion procedure, a 
floating overflow or divide-by-zero exception may occur. A condition handler (HANDL) is 
provided to recover from these exceptions and return the value .FALSE, to the calling pro¬ 
gram. Note that the condition handler is defined as an INTEGER*4 function. 

LOGICAL FUNCTION INVERT <A>N) 

DIMENSION A(N »N> 

EXTERNAL HANDL 

CALL LIB$ESTABLISH(HANDL) ! Establish handler 

INVERT = ♦ T R U E♦ ! Assume success 

♦ (Invert the matrix) 


RETURN 

END 

INTEGER*^ FUNCTION HANDL(SIGARGS» MECHARGS) 

INTEGER*^ S I GARGS(*) » MECHARGS < 5) 

INCLUDE 7 ($SSDEF)' 

HANDL = SS$_RESIGNAL ! Assume resiSnal 

IF (LIB$MATCH_C0ND(SIGARGS(2) » 

1 SS$_FLTOVF »SS*_FLTOVF_F »SS$_FLTDIV>SS$_FLTDIV_F) ♦NE. 0) THEN 
MECHARGS(4) = ♦ FALSE♦ 

CALL SYS$UNNIND( ») 

END IF 

RETURN 

END 

If an exception occurs during the execution of INVERT, the condition handler (HANDL) is 
called. The handler must first determine whether it can deal with the signaled condition 
and therefore tests the condition value (SIGARGS(2)). If the condition is floating overflow 
or floating division-by-zero, the condition handler causes a return from INVERT with a 
.FALSE, value. 

The condition handler uses the unwind procedure to force a return to the procedure that 
called INVERT. The logical value .FALSE, is stored in the saved RO element of the mecha¬ 
nism vector (MECHARGS(4)). This value is used as the function value for INVERT when 
the unwind occurs. The handler calls SYS$UNWIND and returns; the condition handling 
facility then gets control and actually performs the unwind operation. Note that the func¬ 
tion value from the user condition handler (HANDL = SS$_RESIGNAL) is ignored if 
SYS$UNWIND is called. 
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If the exception condition is not a floating overflow or division-by-zero, the condition han¬ 
dler returns a value of SS$_RESIGNAL, indicating that it is unable to deal directly with 
the condition. The immediately preceding procedure activation is then checked for a condi¬ 
tion handler, continuing until an established condition handler or the default condition 
handler is reached. 

Example 2: 

The following example illustrates a condition handler that processes the Run-Time 
Library conditions MTH$_FLOOVEMAT and MTH$_FLOUNDMAT. The purpose of the 
condition handler is to modify the value returned by the Run-Time Library from the 
default value (floating reserved operand -0.0) to the largest representable floating-point 
value, and to suppress the printing of an error message. 

C Main Program 

EXTERNAL HDLR 

CALL LIB$ESTABLISH(HDLR) 


X = EXP(Y) 


END 

INTEGER*^ FUNCTION HDLR(S I GARGS»MECHARGS) 

INTEGER*^ SIGARGS(*) * MECHARGS( 5) 

INCLUDE '($SSDEF) 7 
INCLUDE 7 ($MTHDEF ) 7 

IF (SIGARGS(2) .EQ* MTH$_FL00UEMAT) THEN 
MECHARGS<4> = 7 FFFF7FFF 7 X 

MECHARGS(5) = 7 FFFFFFFF 7 X 

HDLR = SS$_CQNTINUE 

ELSE 

HDLR = SS$_RESIGNAL 
END IF 

RETURN 

END 

When an exception condition occurs, HDLR is called, and it compares the condition value 
(SIGARGS(2)) with MTH$_FLOOVEMAT. If the condition is not MTH$_FLOOVEMAT, 
then SS$_RESIGNAL is returned, and the preceding procedure activations are searched 
for an established handler. 

The recovery technique used in HDLR depends upon a particular coding convention used 
in the Run-Time Library mathematical procedures. If an error is detected in a math 
library procedure, the following steps are performed: 
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1. A default function value is stored in registers RO and R1. Typically, this is the float¬ 
ing reserved operand, -0.0. 

2. An exception condition is signaled by calling LIB$SIGNAL. The contents of regis¬ 
ters RO and R1 are preserved in the mechanism vector (MECHARGS(4), 
MECHARGS(5)). 

3. The value in registers RO and R1 that exists following the signal is stored as the 
function value. 

If the condition is MTH$_FLOOVEMAT, HDLR stores the largest representable floating¬ 
point value in the saved RO and R1 elements of array MECHARGS. HDLR returns the 
function value SS$_CONTINUE, and execution continues in the math library procedure. 
No error message is printed. The values in MECHARGS(4) and MECHARGS(5) are 
restored to RO and R1 by the condition handling facility; they are then returned as the 
function value by the math library procedure. 

Example 3: 

The following example illustrates a user-written condition handling routine that deter¬ 
mines the reason for a system service failure. The example handler only handles one type 
of exception; namely, system service failures. All other exceptions are resignaled, allowing 
them to be handled by the system default handlers. This handler is useful because the sys¬ 
tem traceback handler only indicates that a system service failure occurred, not which 
specific error caused the failure. 

Source Program: 


C SSCOND♦FOR 


C 

C 

C 

C 

C 


This program defines and establishes its own 
condition handling routine to handie system service 
failures* 


IMPLICIT 

EXTERNAL 


INTEGER*^ (A-Z) 
SSHAND 


C 

C 

C 


Establish condition handler 


CALL LIBSESTABLISH (SSHAND) 


o 


c 

c 

c 


Enable system service failure mode 


CALL SYS$SETSFM (ZOAL(l)) 


© 
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c 

c 

c 

c 

c 

c 

c 

c 

c 


c 

c 

c 


c 

c 

c 


c 

c 

c 


c 

c 

c 

c 


c 


Generate a bad system service call 

CALL SYS$0 IQN( > * * * * * * * > * * ) © 

END 

INTEGER*^ FUNCTION SSHAND (SIGNAL * MECH) 0 

This routine is to be used as a condition handler 
for system service failures* 

IMPLICIT 
INTEGER*^ 

INTEGERS 
CHARACTER*120 
INCLUDE 

If not s y s t em 

IF (SIGNAL(2) 

SSHAND 


INTEGER*^ (A-Z) 

S IGNAL(*) » MECH(5) 0 

MSGLEN 

ERRMSG 

7 ($SSDEF) 7 

service fail* resiSnal 

♦NE♦ SS$_SSFA IL) THEN 
= SS$_RESIGNAL 0 


If system service failure 
ELSE 

STAT=SYS$GETMSG( XUAL(SIGNAL<3) ) * MSGLEN* 

1 ERRMSG**) e 

IF ( ♦ NOT ♦ STAT) CALL LIB$ST0P(7,UAL(STAT) ) 

TYPE * 

TYPE ** 'System service call failed with error: 7 
TYPE ** ERRMSG(1:MSGLEN) 

This is where the handler would perform 
corrective measures* 

SSHAND = SS$_RESIGNAL © 

END I F 

RETURN 

END 


Program Output: 

$RUN SSCOND 

System service call failed with error: 0 

ZSYSTEM-F-IUCHAN* invalid I/O channel 

"L S Y S T E M - F - S S F A I L * system service failure exception* s t a t u s = 0 0 0 0 0 1 3 C * 
PC=7FFEDE0G* PSL=03000000 

"L T R A C E - F - T R A C E B A C K * symbolic stack dump follows 

mo d u 1 e name routine name line relative PC absolute PC 

7FFEDE0G 7FFEDE0G 

SSCOND$MAIN SSCOND$MAIN 17 00000020 00000G20 
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Notes to Example 3: 

O LIB$ESTABLISH is used by the main program to establish the condition handler 
SSHAND. 

0 System service failure mode is enabled so errors in system service calls will initi¬ 
ate a search for a condition handler. The system service $SETSFM allows system 
service errors to be signaled. Therefore, the program need not check error status 
after each system service call. The condition handler can respond to all errors gen¬ 
erated by system service calls. 

0 A system service error is generated by not specifying any arguments to $QIOW. 
The LIB$SIGNAL routine could also be used here to generate any exception condi¬ 
tion name to test the condition handler. 

O SSHAND is declared INTEGER*4 FUNCTION to enable it to return a status code 
in RO. 

0 The signal and mechanism arrays must be dimensioned. Notice that the mecha¬ 
nism array always contains five elements, but the signal array varies according to 
the number of additional arguments. 

0 The handler checks the error condition to determine whether it is one it can han¬ 
dle. The LIB$MATCH_COND routine would be useful here if the routine wanted 
to check for one of a collection of conditions. The condition handler should always 
test for specific errors, and handle only those errors for which it is written. Other 
errors should simply be resignaled. 

O The $GETMSG system service is used to translate the error code into the associ¬ 
ated error message. 

0 If the routine did not remedy the exception condition, it will return with a value of 
SS$_RESIGNAL. 

0 Output from user-written condition handling routine. 

0 Output from the system-defined condition handlers. 
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Appendix A 

Compatibility: VAX FORTRAN and FORTRAN-66 


VAX FORTRAN is based on American National Standard FORTRAN-77, X3.9-1978. As a 
result, it contains certain incompatibilities with FORTRAN implementations which are 
based on the previous standard, X3.9-1966. The areas affected are: 

• The minimum iteration count of DO loops 

• The EXTERNAL statement 

• The defaults for the OPEN statement’s BLANK and STATUS keywords 

• The X format edit descriptor 

• The effect of attempting to open a connected unit 

The VAX FORTRAN compiler selects FORTRAN-77 language interpretations by default. 
If you are compiling FORTRAN-66 programs, there are several actions that you can take 
to compensate for language incompatibilities: 

• You can modify your programs so that they produce the intended result with the /F77 
command qualifier or the OPTIONS statement qualifier. Compiler diagnostics help 
you to identify OPEN statements in which an explicit STATUS keyword should be 
added. Linker diagnostics help you to locate EXTERNAL statements that must be 
changed to INTRINSIC statements. 

• You can specify the /NOF77 command qualifier or the OPTIONS statement qualifier 
to select FORTRAN-66 language interpretations. The /NOF77 qualifier affects the 
interpretation of the minimum iteration counts of DO loops, the EXTERNAL state¬ 
ments, and the OPEN statement default for BLANK and STATUS. It does not affect 
the X format edit descriptor. 

• You can redefine the FORTRAN command to include the /NOF77 command qualifier 
or the OPTIONS statement qualifier, thereby selecting FORTRAN-66 language 
interpretations by default. To redefine the FORTRAN command, use a VAX/VMS 
command language symbol definition of the form: 

$ FOR*TRAN :== " FORTRAN/N0F77" 
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You can include this symbol definition in an individual user’s LOGIN command file or 
in a system-wide LOGIN command file. In the latter case, the FORTRAN command is 
redefined for all users. The asterisk (*) in the symbol definition permits you to abbre¬ 
viate the FORTRAN command of three characters (FOR, FORT, and so on). 

This appendix discusses each of the language differences. When possible, it gives an exam¬ 
ple of how you can modify your FORTRAN-66 programs to make them compatible with 
both VAX FORTRAN (FORTRAN-77) and FORTRAN-66. 

A.1 Minimum Iteration Count for DO Loops 

In FORTRAN-77, the body of a DO loop is not executed if the end condition of the loop is 
already satisfied when the DO statement is executed (see Section 2.3.2). In most imple¬ 
mentations of FORTRAN-66, however, the body of a DO loop is always executed at least 
once. 

The /F77 command qualifier controls the interpretation of the minimum iteration count of 
DO loops. 

If you are running a FORTRAN-66 program with the /F77 command qualifier, you may 
want to ensure a minimum loop count of one by modifying the program’s DO statements. 
As an example, assume that a FORTRAN-66 program contains the following statement: 

DO 10, J=I START »I END 

This DO statement specifies that the body of the loop is executed only when IEND is 
greater than or equal to ISTART. However, you could modify the statement to handle a 
situation in which IEND might be less than ISTART. For example: 

DO 10 J=ISTART»MAX<ISTART»IEND) 

The body of this modified DO loop is executed at least once in both FORTRAN-77 and 
FORTRAN-66. 


A.2 EXTERNAL Statement 

In FORTRAN-66, the EXTERNAL statement is used to specify that a symbolic name is the 
name of either a user-defined external procedure or a FORTRAN-supplied function, like 
SQRT or SIN. An EXTERNAL statement is required to pass a procedure name as an 
actual argument. 

In FORTRAN-77, there are two statements that can be used to accomplish this function: 

1. For FORTRAN-supplied intrinsic procedures, like SQRT, the INTRINSIC state¬ 
ment is used. 

2. For user-supplied procedures, the EXTERNAL statement is used. 
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In FORTRAN-66, EXTERNAL SQRT specifies the FORTRAN-supplied real square root 
function. In FORTRAN-77, the identical syntax specifies a user-defined function, and an 
error results at link time if there is no user-defined function called SQRT. 

The /F77 command qualifier controls the interpretation of the EXTERNAL statement. 

When you compile a program with the /N077 qualifier, EXTERNAL*SQRT specifies a 
user-supplied function with the same name that of as a FORTRAN-supplied function. This 
syntax is invalid in FORTRAN-77; the FORTRAN-77 EXTERNAL statement must be 
used instead. 

You cannot modify the EXTERNAL statements in your programs so that the same source 
program works with both FORTRAN-77 and FORTRAN-66 in all cases; you must substi¬ 
tute an equivalent statement: 


FORTRAN-77 


FORTRAN-66 


EXTERNAL USER (no change required) 
INTRINSIC SQRT 
EXTERNAL SQRT 


EXTERNAL USER 
EXTERNAL SQRT 
EXTERNAL *SQRT 


A.3 OPEN Statement Keyword Defaults 

The FORTRAN-66 language did not contain an OPEN statement; however, many imple¬ 
mentations based on FORTRAN-66 do contain an OPEN statement. The defaults for FOR- 
TRAN-77 OPEN statement keywords differ from traditional FORTRAN defaults for the 
attributes which these keywords control. 

A.3.1 OPEN Statement’s BLANK Keyword Default 

In FORTRAN-77, the OPEN statement’s BLANK keyword controls the interpretation of 
blanks in numeric input fields. The FORTRAN-77 default is BLANK = 'NULL 1 ; that is, 
blanks in numeric input fields are ignored. The FORTRAN-66 interpretation of blanks in 
numeric input fields is equivalent to BLANK = 'ZERO'. 

If a logical unit is opened without an explicit OPEN statement, VAX FORTRAN and 
FORTRAN-66 both provide a default equivalent to BLANK = 'ZERO'. 

The BLANK keyword affects the treatment of blanks in numeric input fields read with the 
D, E, F, G, I, O, and Z field descriptors. If BLANK = 'NULL' is in effect, embedded and 
trailing blanks are ignored; the value is converted as if the nonblank characters were 
right-justified in the field. If BLANK = 'ZERO' is in effect, embedded and trailing blanks 
are treated as zeros. The following example illustrates the difference in how blanks in 
numeric input fields are interpreted in FORTRAN-77 and in FORTRAN-66: 
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Program: 

OPEN (UN IT=1 t STATUS='OLD 7 ) 

READ (1 tlO) It J 
10 FORMAT (215) 

END 

Data record: 

AlA2AAAA12 

FORTRAN-77 FORTRAN-66 

1=12 I = 1020 

J = 12 J = 12 

The /F77 command qualifier controls the default value for the BLANK keyword. If your 
program treats blanks in numeric input fields as zeros and you do not want to use the 
/NOF77 qualifier, either include BLANK = 'ZERO' in the OPEN statement or use the BZ 
edit descriptor in the FORMAT statement. 

A.3.2 OPEN Statement’s STATUS Keyword Default 

In FORTRAN-77, the OPEN statement STATUS keyword specifies the initial status of the 
file COLD', 'NEW', 'SCRATCH', or 'UNKNOWN'). The FORTRAN-77 default is 
STATUS = ' UNKNOWN'; that is, an existing file is opened or a new file is created if the file 
does not exist. DIGITAL’s implementation of FORTRAN based on FORTRAN-66 had a 
keyword TYPE which is a synonym for STATUS; however, the default for TYPE is 
TYPE =' NEW'. 

If you use the /F77 command qualifier and you do not specify STATUS (or TYPE) in an 
OPEN statement, the compiler issues an informational message to warn you that it is 
using a default of STATUS = 'UNKNOWN'. It is advisable to include an explicit STATUS 
(or TYPE) keyword in every OPEN statement. If you do not, and the program actually 
expects to write a new file and an old version of the file already exists, then the old file will 
be unintentionally overwritten. 

The /F77 command qualifier controls the default value for the STATUS (or TYPE) 
keyword. 

A.4 X Format Edit Descriptor 

The nX edit descriptor causes transmission of the next character to or from a record to 
occur at the position n characters to the right of the current position. In a FORTRAN-77 
output statement, character positions that are skipped are not modified, and the length of 
the output record is not affected. However, in many FORTRAN-66 implementations, the 
X edit descriptor writes blanks and may extend the output record. For example, the 
statements 

WRITE (1*10) 

10 FORMAT (IX , 7 ABCDEF 7 *T4 >2X » 7 12345 7 #3X) 
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produce the output records 



FORTRAN-77 


FORTRAN-66 


AABCD12345 


AABAAl2345AAA 


The /F77 command qualifier does not affect the interpretation of the X edit descriptor. To 
achieve the FORTRAN-66 effect, change nX to n(' '). 

A.5 Open Operation on a Connected Unit 

In FORTRAN-66, it is an error to execute an OPEN statement on a logical unit that 
already has a file connected to it. 

In FORTRAN-77, the behavior varies as follows: 

• If the filespec specified (or the default) matches that of the currently opened file, the 
new value (if any) of the BLANK keyword is used and the new open request is other¬ 
wise ignored. 

• If the filespecs do not match, the currently open file is closed and the new file is 
opened. 

In neither case for FORTRAN-77 is an error issued. 

There is no way to cause programs compiled with VAX FORTRAN to exhibit the 
FORTRAN-66 behavior. 
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Appendix B 

Compatibility: VAX FORTRAN and PDP-11 FORTRAN 


VAX FORTRAN is a compatible superset of PDP-11 FORTRAN IV and PDP-11 
FORTRAN-77. Most PDP-11 FORTRAN programs can run on VAX without modifications. 
Execution may be affected in some cases, however, due to differences between the hard¬ 
ware architecture of PDP-11 and VAX computers and differences between the IAS/RSX-11 
and VAX/VMS operating environments. Execution also may be affected by the FOR¬ 
TRAN-77 language interpretations described in Appendix C. 

The issues discussed in this section concern differences in language, run-time support, and 
utilities provided in the form of subroutines. 


B.1 Language Differences 

Differences related to language involve: 

• Logical tests 

• Floating-point results 

• Character and Hollerith constants 

• Logical unit numbers 

• Assigned GO TO label list 

• Effect of DISPOSE = 'PRINT' specification 

B.1.1 Logical Tests 

The logical constants .TRUE, and .FALSE, are defined, respectively, as all ones and all 
zeros by both VAX FORTRAN and PDP-11 FORTRAN. The test for .TRUE, and .FALSE, 
differs, however. 

• VAX FORTRAN tests the low-order bit (bit 0) of a logical value. This is the system- 
wide VAX convention for testing logical values. 

• PDP-11 FORTRAN-77 tests the sign bit of a logical value: bit 7 for LOGIC AL*1, bit 15 
for LOGICAL*2, and bit 31 for LOGICAL*4. 
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PDP-11 FORTRAN IV tests the low-order byte of a logical value; all zeros is a .FALSE, 
value, and any nonzero bit pattern is a .TRUE, value. 

In most cases, this difference has no effect. It is significant only for nonstandard FOR¬ 
TRAN programs that perform arithmetic operations on logical values and then make logi¬ 
cal tests on the result. For example: 

LOG ICAL*1 BA 
BA = 3 

IF < BA) GO TO 10 

VAX FORTRAN produces a value of .TRUE., PDP-11 FORTRAN-77 produces .FALSE., 
and PDP-11 FORTRAN IV produces .TRUE. 

B.1.2 Floating-Point Results 

Differences in results from math library routines may occur because of new implementa¬ 
tions of these routines that take advantage of the VAX instruction set. The VAX functions 
produce results with an accuracy equal to or greater than the corresponding PDP-11 func¬ 
tions, but there may be differences. 

In addition, floating-point constants without exponents are not immediately converted to 
REAL*4, as is the case with PDP-11 FORTRAN. This feature provides greater accuracy 
when such constants are used in double-precision expressions. 

B.1.3 Character and Hollerith Constants 

VAX FORTRAN supports both Hollerith and character constants, with the notations 
nHa...aand 'a...a', respectively. In PDP-11 FORTRAN-IV, both notations are usedfor Hol¬ 
lerith constants. (Note that Hollerith constants have no data type; Hollerith constants 
assume a data type consistent with their use.) 

In most cases, the conflicting use of the 'a...a 1 notation is not a problem; VAX FORTRAN 
can determine from the program context whether a character or a Hollerith constant is 
intended. There is, however, one case in which this is not so. In an actual argument list for 
a CALL or function reference, where the subprogram called is a dummy argument, a con¬ 
stant in the 'a...a' notation is always passed as a character constant, never as Hollerith. 
For example, given 

SUBROUTINE S(F) 


CALL F( 'ABCD 7 ) 

if the subroutine referenced by F expects a Hollerith constant (that is, the dummy argu¬ 
ment is a numeric data type), execution is not correct. The actual and dummy arguments 
must agree in data type. This is not the case in the example shown above. To avoid this 
problem, you must change to the nHa...a notation, as follows: 
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SUBROUTINE S(F) 


CALL F(4HABCD) 

B.1.4 Logical Unit Numbers 

If you do not specify a logical unit number in an I/O statement, a default unit number is 
used. The defaults used by VAX FORTRAN differ from those used by PDP-11 FORTRAN- 
77, as shown in Table B-l. 


Table B-l: Default Logical Unit Numbers 


I/O Statement 

PDP-11 Unit 

VAX Unit 

READ 

1 

-4 

PRINT 

6 

-1 

TYPE 

5 

-2 

ACCEPT 

5 

-3 


Note that PDP-11 FORTRAN-77 uses normal logical unit numbers; whereas, VAX 
FORTRAN uses unit numbers that are unavailable to users. This feature prevents con¬ 
flicts between I/O statements that use the default logical unit numbers and those that use 
explicit logical unit numbers. This should have no visible effect on program execution. 

B.1.5 Assigned GO TO Label List 

The labels specified in an assigned GO TO label list are checked by the VAX FORTRAN 
compiler to ensure their validity in the program unit. However, VAX FORTRAN, like 
PDP-11 FORTRAN IV, does not perform a check at run time to ensure that a label actually 
assigned is in the list. PDP-11 FORTRAN-77 does perform this check at run time. 

B.1.6 DISPOSE = PRINT' Specification 

On some PDP-11 systems, the file is deleted after being printed if you specify 
DISPOSE = 'PRINT 1 in an OPEN or CLOSE statement. On VAX FORTRAN, the file is 
retained after being printed. 

B.2 Run-Time Support Differences 

Differences in run-time support between VAX FORTRAN and PDP-11 FORTRAN are 
reflected in run-time error numbers, in run-time error reporting, and in some values for 
OPEN statement keywords. 
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B.2.1 Run-Time Library Error Numbers 


Programs that use the ERRSNS subroutine may need to be modified because certain 
PDP-11 FORTRAN run-time error numbers were either deleted from, or redefined in, the 
VAX Run-Time Library. The error numbers affected are: 

2 through 14 Deleted; these error numbers reported fatal 

PDP-11 hardware conditions. 


37 (INCONSISTENT RECORD 
LENGTH) 

65 (FORMAT TOO BIG FOR 
'FMTBUF') 

72, 73, 82, 83, 84 


75 (FPP FLOATING TO INTEGER 
CONVERSION OVERFLOW) 

86 (INVALID ERROR NUMBER) 

91 (COMPUTED GO TO OUT OF 
RANGE) 


Redefined; continuation is not allowed. 

Deleted; this error cannot occur because space is 
acquired dynamically for run-time formats. 

Redefined; floating-point arithmetic errors and 
math library errors return -0.0 (a hardware 
reserved operand) rather than -I- 0.0. 

Deleted; error number 70 is reported instead. 


Deleted; error number 48 is reported instead. 

Deleted; no error is generated by the VAX hard¬ 
ware when this condition occurs. Program execu¬ 
tion continues in line. 


92 (ASSIGNED LABEL NOT 
IN LIST) 


Deleted; as described in Section B.1.5, VAX 
FORTRAN does not perform this check at run 
time. 


94 (ARRAY REFERENCE Deleted; error number 77 is reported instead. 

OUTSIDE ARRAY) 

95 through 101 Deleted; these error numbers reported PDP-11 

FORTRAN errors that cannot occur in VAX 
FORTRAN. 


B.2.2 Error Handling and Reporting 

VAX FORTRAN differs from PDP-11 FORTRAN-77 in the way that it treats error contin¬ 
uation, I/O errors, and OPEN/CLOSE statement errors. Section 18.1 of Programming in 
VAX FORTRAN describes Run-Time Library error handling. 

B.2.2.1 Continuing After Errors - In PDP-11 FORTRAN, program execution after errors, 
such as floating overflows, normally continues until 15 such errors occur. At that point, 
execution is terminated. VAX FORTRAN, however, sets a limit of one such error; program 
execution normally terminates when the first error occurs. To change this behavior, you 
can take one of the following steps: 
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• Include a condition handler in your program to change the severity level of the error. 
Severity levels of Warning and Error permit continuation. See Chapter 6. 

• Include the ERRSET subroutine (see Section B.3.3). ERRSET alters the Run-Time 
Library’s default error processing to match the behavior of PDP-11 FORTRAN-77. 

B.2.2.2 I/O Errors with I0STAT or ERR Specified - If an IOSTAT or ERR specification was 
included in the I/O statement, VAX FORTRAN neither generates an error message nor 
increments the image error count when an I/O error occurs. Under these circumstances, 
PDP-11 FORTRAN both reports the error and increments the task error count. 

B.2.2.3 OPEN/CLOSE Statement Errors - Unlike PDP-11 FORTRAN, VAX FORTRAN 
reports only the first error encountered in an OPEN or CLOSE statement. PDP-11 
FORTRAN reports all errors detected in processing these statements. 

B.2.3 OPEN Statement Keywords 

For VAX FORTRAN, the space requested by the INITIALSIZE keyword is allocated con¬ 
tiguously, if possible, on what is called a best-try basis. That is, if you specify an 
INITIALSIZE value and sufficient contiguous space is available, allocation is contiguous. 
If there is not enough contiguous space, allocation is noncontiguous. 

For PDP-11 FORTRAN-77, allocation of contiguous or noncontiguous space depends on 
the sign of the value specified for the INITIALSIZE and EXTENDSIZE keywords. To be 
compatible with PDP-11 FORTRAN, VAX FORTRAN uses the absolute value of the user- 
supplied value. 

B.3 Utility Subroutines 

There are a number of utility subroutines available for use with PDP-11 FORTRAN-77. 
All are supplied as part of PDP-11 FORTRAN-77, as described in the PDP-11 
FORTRAN-77 User's Guide. 

Six of these subroutines are supplied as a standard part of VAX FORTRAN (see Program¬ 
ming in VAX FORTRAN). These subroutines are: 

DATE 

ERRSNS 

EXIT 

IDATE 

SECNDS 

TIME 

The remaining subroutines are provided only for purposes of compatibility; most have 
been superseded by features included in VAX FORTRAN, while others have little applica¬ 
bility on VAX systems. Sections B.3.1 through B.3.11 describe these routines, which are: 
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ASSIGN 

CLOSE 

ERRSET 

ERRTST 

FDBSET 

IRAD50 

RAD50 

RAN 

RANDU 

R50ASC 

USEREX 

B.3.1 ASSIGN Subroutine 

The ASSIGN subroutine is used to supply device or file-name information for a logical 
unit. That is, it allows a device or file to be assigned to a logical unit. The assignment 
remains in effect until the program terminates or until the logical unit is closed by a 
CLOSE statement. 

The ASSIGN subroutine must be called before the first I/O statement is issued for that 
logical unit. 

The CALL FDBSET, CALL ASSIGN, and DEFINE FILE statements can be used together, 
but none can be used in conjunction with the OPEN statement or INQUIRE statement for 
the same unit. 

There are two other ways to assign a device or a file name to a logical unit number: specify 
the FILE keyword in an OPEN statement or use the ASSIGN system command. 

A call to ASSIGN has the form: 

CALL ASSIGN (n[,name][,icnt]) 
where: 

n 


is an integer value specifying the logical unit number, 
name 

is a variable, array, array element, or character constant containing any standard file 
specification. 

icnt 


is an INTEGER*2 value that specifies the number of characters contained in the 
string name. 
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Note: 


If only the unit number is specified, all previously specified file/device associations 
pertaining to that unit are nullified and the defaults become effective. If icnt is omit¬ 
ted (or specified as zero), the file specification (if specified) is read until the first ASCII 
null character is encountered. If the icnt argument is specified, the name argument 
must also be specified. 

B.3.2 CLOSE Subroutine 

The CLOSE subroutine closes the file currently open on a logical unit. A call to CLOSE has 
the form: 

CALL CLOSE (n) 

where: 

n 


is an integer value specifying the logical unit. 

After the file is closed, the logical unit again assumes the default file-name specification. 

B.3.3 ERRSET Subroutine 

The ERRSET subroutine determines the action taken in response to an error detected by 
the Run-Time Library. The VAX condition handling facility provides a more general 
method of defining actions to be taken when errors are detected (see Chapter 6). A call to 
ERRSET has the form: 

CALL ERRSET (number, contin, count, type, log, maxlim) 
where: 

number 

is an integer value specifying the error number. 

contin 

is a logical value: 

.TRUE. Continue after error is detected. 

.FALSE. Exit after error is detected. 

count 

is a logical value: 

.TRUE. Count the error against the maximum error limit. 

.FALSE. Do not count the error against the maximum error limit. 
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type 


is a logical value: 

.TRUE. Pass control to an ERR transfer label, if specified. 

.FALSE. Return to routine that detected the error, for default error recovery. 

log 

is a logical value: 

.TRUE. Produce an error message for this error. 

.FALSE. Do not produce an error message for this error. 

maxlim 

is a positive INTEGER*2 value specifying the maximum error limit. The default is 
set to 15 at program initialization. 

Notes: 

1. The error action specified for each error is independent of other errors. 

2. Null arguments are legal for all arguments, except number arguments, and have 
no effect on the current state of that argument. 

3. An external reference to ERRSET or ERRTST causes a special PDP-11 FORTRAN 
compatibility error handler to be established before the main program is called. 
This special error handler transforms the executing environment to approximate 
that of PDP-11 FORTRAN. 

B.3.4 ERRTST Subroutine 

The ERRTST subroutine checks for a specific error. To perform appropriate actions in 
response to errors, you should establish a condition handler, as described in Chapter 6. A 
call to ERRTST has the form: 

CALL ERRTST (i j) 

where: 

i 

is an integer value specifying the error number. 

j 

is a variable used for return value of error check: 
j = 1: Error i has occurred, 
j = 2: Error i has not occurred. 
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Notes: 


1. ERRTST resets the error flag for the specified error. 

2. ERRTST is independent of the ERRSET subroutine. Neither subroutine has any 
direct effect on the other. 

See also Note 3 under ERRSET. 

Example: 

CALL ERRTST <43 #J) 

GO TO (10 #20)J 
20 CONTINUE 

If error 43 is detected, a branch is taken to statement 10 (J = 1); if error 43 is not detected, 
control passes to statement 20 (J = 2). 


B.3.5 FDBSET Subroutine 


The FDBSET subroutine is used to specify special I/O options. The recommended method 
of specifying I/O options is the OPEN statement. A call to FDBSET has the form: 

CALL FDBSET (unit[,acc,share,numbuf,initsz,extend]) 
where: 

unit 

is an integer value specifying the logical unit. 


acc 


is a character constant 
'READONLY' 
'NEW' 

'OLD' 

'APPEND' 

'UNKNOWN' 


specifying the access mode to be used: 
Establish read-only access. 

Create a new file. 

Access an existing file. 

Extend an existing sequential file. 

Try 'OLD'; if no such file exists, use 'NEW'. 


share 

is a character constant 'SHARE' indicating that shared access is allowed. 


numbuf 

is an INTEGER*2 value specifying the number of buffers to be used for multibuf- 
fered I/O. 


initsz 

is an INTEGER*2 value specifying the number of blocks initially allocated for a 
new file. 

extend 

is an INTEGER*2 value specifying the number of blocks by which to extend a file. 
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Notes: 

1. FDBSET can be used only before issuing the first I/O statement for the unit. 

2. CALL FDBSET, CALL ASSIGN, and the DEFINE FILE statement can be used 
together, but none can be used in conjunction with the OPEN statement or 
INQUIRE statement for the same unit. 

3. The unit argument must be specified. All other arguments are optional. 

B.3.6 IRAD50 Subroutine 

The IRAD50 subroutine is used to convert Hollerith data to Radix-50 form. IRAD50 may 
be called as a function subprogram if the return value is desired (format 1, below), or as a 
subroutine if the return value is not desired (format 2, below). 

• Format 1: n = IRAD50 (icnt,input,output) 

• Format 2: CALL IRAD50 (icnt,input,output) 
where: 

n 


for function, is an INTEGER*2 value indicating how many characters are converted. 

icnt 


is an INTEGER*2 value specifying the maximum number of characters to be 
converted. 

input 

is a Hollerith string to be converted to Radix-50. 

output 

is a numeric variable or array element where the Radix-50 results are stored. 
Notes: 

1. Three Hollerith characters are packed into each output word. The number of out¬ 
put words is computed by the expression: 

(ICNT + 2) /3 

Thus, if a value of 4 is specified for icnt, two output words will result, even if an 
input string of only one character is converted. 

2. Scanning of the input characters terminates on the first non-Radix-50 character in 
the input string. 


B-10 


Compatibility: VAX FORTRAN and PDP-11 FORTRAN 





B.3.7 RAD50 Function 


The RAD50 function subprogram provides a simplified way to encode six Hollerith charac¬ 
ters as two words of Radix-50 data. It has the form: 

RAD50 (name) 

where: 

name 

is a numeric variable name or array element corresponding to a Hollerith string. 

Note: 

The RAD50 function is equivalent to 

FUNCTION RAD50 (A) 

CALL IRAD50 (G »A »R A D 5 0 ) 

RETURN 

END 


B.3.8 RAN Function 

The RAN function subprogram returns a pseudo-random number as the function value. It 
has the form: 

RAN (il,i2) 

where: 

il,i2 

are INTEGER*2 variables or array elements that contain the seed for computing the 
random number. 

Notes: 

1. The values of il and i2 are updated during the computation to contain the updated 
seed. 

2. The algorithm for computing the random number value is identical to the 
algorithm used in the RANDU subroutine (see Section B.3.9). 

3. The RAN function is equivalent to: 

FUNCTION RAN (II ,12) 

CALL RANDU (11*12 »RAN) 

RETURN 

END 

4. This RAN function is distinguished from the single argument RAN function by the 
number of arguments. The single argument form uses a statistically better 
algorithm and is recommended when compatibility with PDP-11 FORTRAN is not 
important. 
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B.3.9 RANDU Subroutine 


The RANDU subroutine computes a pseudo-random number as a single- precision value 
uniformly distributed in the range: 

0.0 .LE. value .LT. 1.0 

A call to RANDU has the form: 

CALL RANDU (il,i2,x) 

where: 

il,i2 

are INTEGER*2 variables or array elements that contain the seed for computing the 
random number. 

x 

is a real variable or array element where the computed random number is stored. 
Notes: 

1. The values of il and i2 are updated during the computation to contain the updated 
seed. 

2. The algorithm for computing the random number value is as follows: 

If II = 0,12 = 0, set generator base 

X (ri + l ) = 2**1G + 3 

Otherwise 

X ( n +1 ) = (2**16+3)* X(r.) mod 2**32 

Store generator base X(n = 1) in 11,12. 

Result is X(n + 1) scaled to a real value Y(n= 1), for 0.0 .LE. Y(n= 1) .LT. 1. 

B.3.10 R50ASC Subroutine 

The R50ASC subprogram converts Radix-50 values to Hollerith strings. A call to R50ASC 
has the form: 

CALL R50ASC (icnt,input,output) 
where: 

icnt 

is an INTEGER*2 value specifying the number of ASCII characters to be produced. 

input 

is a numeric variable or array element containing the Radix-50 data. 
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output 

is a numeric variable or array element where the Hollerith characters are to be 
stored. 

Notes: 

1. The number of words of input equals (icnt + 2)/3. 

2. If the undefined Radix-50 code is detected or if the Radix-50 word exceeds 174777 
(octal), question marks are placed in the output location. 

B.3.11 USEREX Subroutine 

The USEREX subroutine specifies a routine to be called as part of the program termina¬ 
tion process. This allows clean-up operations in non-FORTRAN routines. 

You can establish a termination handler directly by calling the system service routine 
SYS$DCLEXH. A call to USEREX has the form: 

CALL USEREX (name) 

where: 

name 

specifies the routine to be called. 

Notes: 

1. The routine name must appear in an EXTERNAL statement in the program unit. 

2. The user exit subroutine is called as a VAX/VMS termination handler. See the 
VAX/VMS System Services Reference Manual for information regarding termina¬ 
tion handlers. 

3. Do not attempt to perform FORTRAN I/O operations as part of an exit handler. 
The FORTRAN I/O system provides its own exit handling functions, such as file 
closing, and user-specified I/O operations may not work as expected. 
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Appendix C 


The Contents of the FORTRAN System Library 
FORSYSDEF 

Table C-l is a list of the modules contained in the FORTRAN system library FORSYSDEF. 
The modules consist of definitions, in FORTRAN source code, of related groups of system 
symbols that can be used in calling VAX/VMS system services. FORSYSDEF also contains 
modules that define the condition symbols for Run-Time Library procedures. 

Section 3.3.1 describes the procedure for accessing the modules listed below from a 
FORTRAN program. Section 6.8 describes condition values and symbols. 

Table C-l: Contents of System Library FORSYSDEF 


Module Name 

Description 

$ACCDEF 

$ACEDEF 

$ACLDEF 

$ACRDEF 

$ARGDEF 

$ARMDEF 

$ATRDEF 

$BRKDEF 

$CHFDEF 

$CHKPNTDEF 

$CHKPRO 

$CHPDEF 

$CLIDEF 

Accounting manager request type codes 

Access control list entry structure definitions 

Access control list interface definitions 

Accounting record definitions 

Argument descriptor for object language procedure records 

Access rights mask longword definitions 

File attribute list description — used to read and write file attributes 

Breakthru ($BRKTHRU) system service input definitions 

Condition handling argument list offsets 

Create checkpointable processes flag definitions 

Item definitions for $CHKPRO (check protection) system services 

Check protection ($CHKPRO) system service definitions 

Command language interface definitions — define the offset values for structures 
used to communicate information to CLI 


(Continued on next page) 
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Table C-l: (Cont.) Contents of System Library FORSYSDEF 


Module Name 

Description 

$CLISERVDEF 

$CLIVERBDEF 

$CLSDEF 

CLI service request code definitions 

CLI generic verb codes definitions 

Security classification mask block — contains security and integrity level 
categories for nondiscretionary access controls 

$CQUALDEF 

$CRDEF 

$CREDEF 

$CRFDEF 

$DCDEF 

$DEVDEF 

$DIBDEF 

$DMPDEF 

$DMTDEF 

$DSCDEF 

$DSTDEF 

$DVIDEF 

$ENVDEF 

$EOMDEF 

$EOMWDEF 

$EPMDEF 

$EPMWDEF 

Backup command qualifier definitions 

Card reader status bits 

Create options table definitions for library facility 

CRF$—INSRTREF argument list 

Device adapter, class, and type definitions 

I/O device characteristics 

Device information block definitions 

Header block definitions of system dump file 

Flag bits for the Dismount ($DISMOU) system service 

Descriptor type definitions 

Debug symbol table definitions 

Device and volume information data identifier definitions 

Environment definitions in object file 

End of module record in object/image files 

End of module record in object/image with word of psect value 

Global symbol definition record in object file — entry point definitions 

Global symbol definition record in object file — entry point definitions with word 
of psect value 

$ERADEF 

$FABDEF 

$FIBDEF 

$FIDDEF 

$FMLDEF 

Erase type code definitions 

RMS File access block definitions 

File identification block definitions 

File ID structure 

Formal argument definitions appended to procedure definitions in global symbol 
definition record in object file 

$FORDEF 

$FORIOSDEF 

$FSCNDEF 

$GPSDEF 

$GSDEF 

Condition symbols for FORTRAN-specific Run-Time Library 

FORTRAN IOSTAT error numbers 

Descriptor codes for SYS$FILESCAN 

Global symbol definition record in object file — psect definitions 

Global symbol definition (GSD) record in object file 
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Table C-ls (Cont.) Contents of System Library FORSYSDEF 


Module Name 

Description 

$GSYDEF 

$HLPDEF 

$IACDEF 

$IDCDEF 

$IODEF 

$JPIDEF 

$KGBDEF 

$LADEF 

$LBRCTLTBL 

$LBRDEF 

$LCKDEF 

$LEPMDEF 

Global symbol definition record in object file — symbol definitions 

Data structures for help processing 

Image activation control flags 

Object file IDENT consistency check structures 

I/O function codes 

Job/process information request type codes 

Key grant block definitions — formats of records in rights database file 
Laboratory peripheral accelerator device types 

Librarian control table definitions 

Library type definitions 

Lock manager definitions 

Global symbol definition record in object file — module local entry point defini¬ 
tions 

$LHIDEF 

$LIBCLIDEF 

$LIBDCFDEF 

$LIBDEF 

$LKIDEF 

$LNKDEF 

$LNMDEF 

$LPDEF 

$LPRODEF 

Library header information array offsets 

Definitions for LIB$ CLI callback procedures 

Definitions for LIB$DECODE_FAULT procedure 

Condition symbols for the general utility library 

Get lock information data identifier definitions 

Linker option record definition in object file 

Logical name flag definitions 

Line printer characteristic codes 

Global symbol definition record in object file — module local procedure definition 
in object file 

$LSDFDEF 

$LSRFDEF 

$LSYDEF 

$MHDEF 

$MNTDEF 

$MSGDEF 

$MTDEF 

Module local symbol definition in object file 

Module local symbol reference in object file 

Module local symbol definition 

Module header record definition in object file 

Flag bits and function codes for the MOUNT system service 

Symbolic names to identify mailbox message senders 

Magnetic tape characteristic codes 
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Table C-l: (Cont.) Contents of System Library FORSYSDEF 


Module Name 

Description 

$MTHDEF 

$NAMDEF 

$NSARECDEF 

$OBJRECDEF 

$OPCDEF 

$OPCMSG 

$OPDEF 

$OPRDEF 

$OTSDEF 

$PCCDEF 

$PLVDEF 

$PQLDEF 

$PR730DEF 

$PR750DEF 

$PR780DEF 

$PRCDEF 

$PRDEF 

$PRODEF 

$PROWDEF 

Condition symbols from the mathematical procedures library 

RMS name block field definitions 

Security auditing record definitions 

Object language record definition 

Operator communication manager request type codes — return status codes 
OPCOM message definitions 

Opcode values 

Operator communications message types and values 

Language-independent support procedure (OTS$) return status codes 
Printer/terminal carriage control specifiers 

Privileged library vector definitions 

Quota types for process creation quota list 

VAX 11/730 processor specific definitions 

VAX 11/750 processor specific definitions 

VAX 11/780 processor specific definitions 

Create process ($CREPRC) system service status flags and item codes 

Processor register definitions 

Global symbol definition record in object file — procedure definition 

Global symbol definition record in object file — procedure definition with word of 
psect value 

$PRTDEF 

$PRVDEF 

$PSLDEF 

$PSWDEF 

$QUIDEF 

$RABDEF 

$RMEDEF 

$RMSDEF 

$SBKDEF 

$SCRDEF 

Protection field definitions 

Privilege bit definitions 

Processor status longword (PSL) mask and symbolic names for access modes 

Processor status word mask and field definitions 

Get queue information service definitions 

RMS record access block definitions 

RMS escape definitions 

RMS return status codes 

Open file statistics block 

Screen package interface definitions 
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Module Name 

Description 

$SDFDEF 

$SDFWDEF 

$SECDEF 

$SFDEF 

$SGPSDEF 

Symbol record in object file 

Symbol record in object file with word of psect value 

Attribute flags for private/global section creation and mapping 

Stack frame offset definitions 

Global symbol definition record in object file — P-section definition in shareable 
image 

$SHRDEF 

$SJCDEF 

$SMGDEF 

$SMGTRMPTR 

$SMRDEF 

$SRFDEF 

$SRMDEF 

$SSDEF 

$STRDEF 

$STSDEF 

$SYIDEF 
$S Y SSRVNAM 

$TIRDEF 

$TPADEF 

$TRMDEF 

$TT2DEF 

$TTDEF 

$UICDEF 

$USGDEF 

Definitions for shared messages 

Send to job controller service definitions 

Definitions for RTL screen management 

Terminal capability pointers for RTL SMG$ facility 

Define symbiont manager request codes 

Global symbol definition record in object file — symbol reference definitions 

SRM hardware symbol definitions 

System service failure and status codes 

String manipulation procedures (STR$) return status codes 

Status codes and error codes 

Get system information data identifier definitions 

System service entry point descriptions 

Text information and relocation record in object file 

TPARSE control block 

Define symbols to the item list QIO format 

Terminal special symbols 

Terminal device characteristic codes 

Format of user identification code (UIC) 

Disk usage accounting file produced by ANALYZE/DISK_STRUCTURE 


(Continued on next page) 


The Contents of the FORTRAN System Library FORSYSDEF 


C-5 







Table C-ls (Cont.) Contents of System Library FORSYSDEF 


Module Name 

Description 

$XABALLDEF 

$XABCXFDEF 

$XABCXRDEF 

$XABDATDEF 

$XABDEF 

$XABFHCDEF 

$XABJNLDEF 

$XABKEYDEF 

$XABPRODEF 

$XABRDTDEF 

$XABSUMDEF 

$XABTRMDEF 

$XADEF 

$XFDEF 

$XKDEFDEF 

$XKSTSDEF 

$XMDEF 

$XWDEF 

Allocation XAB definitions 

RMS context XAB associated with FAB 

RMS context XAB associated with RAB 

Date/time XAB definitions 

Definitions for all XABs 

File header characteristics XAB definitions 

Journal XAB definitions 

Key definitions XAB field definitions 

Protection XAB field definitions 

Revision date/time XAB definitions 

Summary XAB field definitions 

Terminal control XAB field definitions 

DR11-W definitions for device specific characteristics 

DR32 device characteristic codes 

3271 device status block 

Definitions for 3271 line status block (returned by IO$_RDSTATS) 

DMC-11 device characteristic codes 

System definition for software DDCMP 
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Appendix D 

Examples of Use of System Services 


This appendix contains examples that involve accessing VAX/VMS system services. The 
individual examples perform the following operations: 

1. Calling RMS Procedures 

2. Synchronizing Processes Using an AST Routine 

3. Accessing Devices Using Synchronous I/O 

4. Communicating with Other Processes 

5. Sharing Code and Data 

6. Gathering and Displaying Data at Terminals 

7. Creating, Accessing, and Ordering Files 

8. Measuring and Improving Performance 

9. Accessing Help Libraries 

10. Creating and Managing Other Processes 
The examples are presented under these headings in the order shown here. 

D.1 Calling RMS Procedures 

When you explicitly call an RMS system service, the order of the arguments in the call 
must correspond with the order shown in the VAX Record Management Services Reference 
Manual. You must use commas to reserve a place in the call for every argument. If you 
omit an argument, the procedure uses a default value of zero. For more information on 
calling RMS system services, see Chapter 4. 

The procedure name format is SYS$procedure_name when calling an RMS routine from 
FORTRAN. The following example shows a call to the RMS procedure SYS$SETDDIR. 
This RMS procedure sets the default directory for a process. 
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Source Program: 

C SETDDIR♦FOR 

C 

C This program calls the RMS procedure $SETDDIR to charge 

C the default director 4 / for the process* 

C 

IMPLICIT INTEGER (A - Z) 

CHARACTER*17 DIR /'CEX.PROG.FOR 3 ' / 

STAT = SYS$SETDDIR (DIR » ») 

IF (♦NOT♦ STAT) TYPE *t 'ERROR' 

END 


o 

© 


$ DIRECTORY © 

Di rector 4 / NORK $ : C EX * PROG * FOR * CALL 3 


BASSUM.BAS51 

getmsg.exe;i 

MACSUM.MAR 5 2 
SHOWSUM♦FOR 5G 


BASSUM.OBJ51 
GETMSG♦FOR 5 14 
SETDDIR♦FOR 5 3 
SHOWSUM.LIS 52 


COBSUM.COM51 
GETMSG♦L I S 5 2 
SETDDIR.L I S 5 1 
SHOWSUM.OBJ52 


DOCOMMAND.FOR 52 
GETMSG.0BJ51 
SHOWSUM.EXE5 1 


Total of 15 files. 

Sample Use: 

$ FORTRAN SETDDIR 
$ LINK SETDDIR 
$ RUN SETDDIR 

$ DIRECTORY O 

Director 4 / WORK $ : C EX . PROG ♦ FOR 3 


CALL♦DIR 51 
HAND♦DIR 51 
RMS.DIR 51 


COMU♦DIR 51 
INTR.DIR 51 
SHAR.DIR51 


DEUC.DIR51 
LNKR.DIR 51 
SYNC.DIR51 


FIL♦DIR 5 1 
MNAG.DIR5 1 
TERM.DIR 5 1 


Total of 12 files. 

Notes: 


© The default directory name is initialized into a CHARACTER variable. 

© The call to $SETDDIR contains one argument, the directory name, which is passed 
by descriptor, the default argument passing mechanism for CHARACTERS. The 
omitted arguments are optional, but commas are necessary to reserve places in the 
argument list. 

© The DIRECTORY command shows that the default directory is: 

WORK $:CEX.04PROG♦FOR.CALL 3 
which contains the file SETDDIR.FOR. 

o Another DIRECTORY command shows that the default directory has changed. 
The directory is set to: 

WORK $:C EX.PROG.F0R3♦ 
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D.2 Synchronizing Processes Using an AST Routine 


The methods for requesting and declaring an AST procedure are illustrated in the follow¬ 
ing example. 

Source Program: 


c 

C AST PROC♦FOR 

C 

C This pros raw sets a 10-second timer which requests 

C an AST* The main program then performs arithmetic 

C operations for the user t interrupted after 10 

C seconds by the timer AST* 

C 

IMPLICIT 
INCLUDE 
EXTERNAL 
DIMENSION 
CHARACTER*9 
C 

C Convert delay interval to binary and set timer 

C 

RESULT = SYS$BINTIM( DELAY» BIN-DELAY) 

IF (♦NOT♦ RESULT) CALL LIB$ST0P( XOAL( RESULT)) 
STATUS = SYS$SETI MR( »BIN-DELAY * AST_PR0C») © 

IF (♦NOT♦ STATUS) CALL LIB$ST0P( ZUAL< STATUS)) 

C 

C Prompt user for 2 numbers and multiply them 

C 

100 TYPE * * 'Enter two integers to be multiplied* ' 

TYPE * t '(Enter two zeros to quit)' 

ACCEPT * » NUM1 > NUM2 
PRODUCT = NUM1 * NUM2 
IF (PRODUCT .EQ. 0) GO TO 200 
TYPE *» 'The product is:'» PRODUCT 
GO TO 100 
200 CONTINUE 

END 
C 
C 

SUBROUTINE AST-PROC 


INTEGER*^ (A-Z) 

' ( $ S Y S S R 0 N A M ) ' 

AST-PROC 
BIN-DELAY(2) 

DELAY /'0 ::10.00'/ Q 


C 

C 

C 

C 


This subprogram is called as an AST procedure* 
It prints the current time at the terminal* 


IMPLICIT 
PARAMETER BRK$C 
CHARACTER*23 
CHARACTER*18 
CHARACTER*41 
INTEGER*2 


INTEGER (A-Z) 
DEUICE = 1 
CUR-TIME 
MSG /' The 

OUT-MSG 
IOSB(4) 


time is now: ' / 
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c 

c 

STATUS = LIB$DATE_TI ME( CUR_TIME) 

IF (.NOT. STATUS) CALL LIB$STOP( 7JJ AL< STATUS)) 

OUT-MSG = MSG // CUR-TIME 
STYPE = BRK$C-DEVICE 

STATUS = SYS$BRKTHRUW ('U'AL(l) » OUT-MSG, 7 SYS$OUTPUT'» 

1 7, U A L ( S T Y P E ) * XREFdOSB )******) 

IF (.NOT. STATUS) CALL LIB$STOP( *UAL< STATUS)) 

IF (.NOT. IOSB(l)) CALL LI B$STOP ( 2.UAL ( IOSB ( 1 ) ) ) 

C 

RETURN Q 

END 

Sample Use: 

$ RUN ASTPROC 

Enter two integers to be multiplied. 

(Enter two zeros to quit) 

12 * 12 

The product is: 144 

Enter two integers to be multiplied. 

(Enter two zeros to quit) 

23 » 45 

The time is now: 1 4-Ju1y- 1984 13:25:10.71 Q 

The product is: 1035 

Enter two integers to be multiplied. 

(Enter two zeros to quit) 

0 » 0 
$ 

Notes: 

O Any variables or arrays that are used or modified by the AST routine should be 
declared VOLATILE in the other routines that reference them. See Section 1.3.2.2 
in this manual and Section 8.16 of Programming in VAX FORTRAN . 

O The third parameter in the $SETIMR call is the address of the entry point of the 
AST procedure to be executed when the timer expires. Note that the AST proce¬ 
dure must be declared as EXTERNAL. 

O If the user wants the AST routine to be executed repeatedly, rather than just once, 
the timer would be reset at the end of the AST routine. 

O When the AST is delivered, the AST routine interrupts the program and outputs a 
message. 
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D.3 Accessing Devices Using Synchronous I/O 


The following example performs output to a terminal via the SYS$QIOW system service. 


Source Program: 


C 0 I ON♦FOR 

C 

C This program illustrates the use of the $ 0 I 0 N 

C system service to perform synchronous I/O to 

C a terminal* 

C 

IMPLICIT 
INCLUDE 
INCLUDE 
CHARACTER*21 
CHARACTER*11 
INTEGER*2 
C 

C Assign the channel number 

C 

STAT = SYS$ASSIGN (TERMINAL t TERM_CHAN t t ) 

IF (♦NOT♦ STAT) CALL LIB$STOP (XUAL(STAT)) Q 

C 

C Output the message twice 

C 

DO 1 = 1 ,2 

STAT = SYS$QI ON 

1 
1 
1 
1 


( X U A L ( 1 ) »XUAL(TERM-CHAN) > © 

XUAL(I0$_NRITEUBLK) >IOSB » » » 

XREF(TEXT-STRING) » 

'/.UAL (21 ) > » 

'/.UAL (32) » > ) 


INTEGER*^ (A - Z) 

7 ( $ S Y S S R U N A M ) 7 
7 ($ IODEF) 7 

TEXT-STRING /'This is from a SYS$QI0N. 7 / O 
TERMINAL / 7 SYS$COMMAND 7 / 

TERM-CHAN »I0SB(4> 


IF (.NOT* STAT) CALL LIB$STOP (XUAL(STATUS)) 

IF (.NOT* IOSB(1) ) CALL LIB$STOP (XUAL(IOSB(1) ) ) 

ENDDO 

END 

Sample Use: 


$ FORTRAN QI ON 
$ LINK 01 ON 
$ RUN 01 ON 

This is from a SYS$QION* 
This is from a SYS$QION* 


Notes: 

O If SYS$QIO and a SYS$WAITFR are used instead of SYS$QIOW, you must use a 
VOLATILE declaration for any program variables and arrays that can be changed 
while the operation is pending. 
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Q TERM_CHAN receives the channel number from the SYS$ASSIGN system 
service. 

The process permanent logical name SYS$COMMAND is assigned to your termi¬ 
nal when you log in. The SYS$ASSIGN system service will translate the logical 
name to the actual device name. 

Q SYS$QIO and SYS$QIOW accept the CHAN argument by immediate value, 
unlike SYS$ASSIGN, which requires that it be passed by reference. Note the use 
of %VAL in the call to SYS$QIOW but not in the call to SYS$ASSIGN. 

The function IO$_WRITEVBLK requires values for parameters PI, P2, and P4. 

• PI is the starting address of the buffer containing the message. So, 
TEXT_STRING is passed by reference. 

• P2 is the number of bytes to be written to the terminal. A 21 is passed, since it is 
the length of the message string. 

• P4 is the carriage control specifier; a 32 indicates single space carriage control. 

A SYS$QIOW is issued, ensuring that the output operation will be completed 
before the program terminates. Change the SYS$QIOW to a SYS$QIO and see 
what happens. 


D.4 Communicating with Other Processes 


The following example shows how to create a global pagefile section and how two processes 
can use it to access the same data. One process executes the program PAGEFIL1 which 
creates and writes to a global pagefile section. PAGEFIL1 then waits for a second process 
to update the section. The second process executes PAGEFIL2 which maps and updates the 
pagefile section. Because PAGEFIL2 maps to the temporary global pagefile section created 
in PAGEFIL1, PAGEFIL1 must be run first. The two processes coordinate their activity 
through common event flags. 

Source Program: 

C PAGEFIL1.F0R 


C 

C 

C 

C 


This program creates and maps a global page frame section 
Data in the section is accessed through an array* 


IMPLICIT INTEGER*4 

INCLUDE 

INCLUDE 

DIMENSION 

DIMENSION 

COMMON /MYCOM/ 

INTEGERS 

CHARACTER*^ 

VOLATILE /MYCOM/ 


( A-Z) 

7 <*SECDEF) 7 
7 <$SYSSRVNAM) 
MY_ADR(2) 
SYS_ADR(2) 

I ARRAY(50) 

IOSB(4) 

NAME/ 7 GSEC 7 / 


o 


© 
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C 

C Associate with common cluster M Y C L U S 

C 

CALL SYS$ASCEFC ( 7UAL ( G4 ) * 7 MYCLUS 7 * * ) © 

C 

C Get the starting and end ins addresses of the section 

C 

MY_ADR ( 1 ) = 7L0C ( I ARRAY ( 1 ) ) Q 

MY-ADR(2) = 7,L□ C ( I ARRA Y ( 50 ) ) 

SEC_FLAGS = SEC$M_PAGFIL.OR.SEC$M_GBL.OR.SEC$M_WRT.OR.SEC$M_DZRQ 
C 

C Create and map the temporary S1 o b a 1 section 

C 

STATUS = SYS$CRMPSC(MY_ADR »S Y S _ A D R * * 7 U A L ( S E C _ F L A G S ) * Q 
1NAME * * *70AL(0) *7UAL( 1) t t t) 

IF (♦NOT♦ STATUS) CALL LIB$STOP(70AL(STATUS)) 

C 

C Manipulate the data in the slobal section © 

C 

DO 10 I =1 ,50 
I ARRAY(I) = I 
10 CONTINUE 

C 

STATUS = S Y S $ S E T E F(7 0 A L(7 2) ) 

IF (♦NOT♦ STATUS) CALL LIB$STOP(70AL(STATUS)) 

TYPE *,'HaitinS for PAGEFIL2 to update section 7 
STATUS = SYS$NA ITFR(70AL(73) ) 

C 

C Print the modified p a 3 e s 

C 

TYPE * * 'Modified data in the 3 1 o b a 1 section:' 

WRITE (6*100) (I ARRAY(I) » 1 = 1*50) 

100 FORMAT(1015) 

END 

C PAGEFIL2.F0R 

C 

C This program maps and modifies a 3 1o b a 1 section 

C after PAGEFIL1 creates the section. Programs 

C PAGEFIL1 and PAGEFIL2 synchronize the processing 

C of the 3 1 o b a 1 section through the use of common 

event f 1 a 3 s ♦ 

IMPLICIT INTEGER*^ 

INCLUDE 
INCLUDE 
DIMENSION 
COMMON /MYCOM/ 

OOLATILE /MYCOM/ 

C 

MY-ADR(1) = 7L0C(I ARRAY(1) ) 

MY-ADR(2) = 7L0C(I ARRAY(50) ) 


(A - Z) 

' ($SECDEF) ' 

' ( $ S Y S S R 0 N A M ) 
MY_ADR(2) 

I ARRAY(50) 
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c 

C Associate with common cluster MYCLUS and wait for 

C event flag to be set 

C 

STATUS = SYS$ASCEFC(XUAL(64) » 7 MYCLUS 7 t ») © 

IF (.NOT. STATUS) CALL LIB$STOP (7.UAL(STATUS)) 

STATUS = SYS$WAITFR <*.UAL<72)) 

IF (.NOT. STATUS) CALL LIB$STOP ( VJJ AL ( ST ATUS ) ) 

C 

C Set flag to allow section to be written 

C 

FLAGS = SEC$M_WRT 
C 

C Map the global section 

C 

STATUS = SYS$MGBLSC(MY_ADR » * * 7. U A L ( F L A G S ) * 7 G S E C 7 * * ) © 

IF (.NOT. STATUS) CALL LIB$STOP (7,UAL(STATUS)) 

C 

C Print out the data in the g 1 o ba 1 section and 

C multiply each value by two 

C 

TYPE * * 'Original data in the global section: 7 
WRITE (6*100) (I ARRAY(I) » 1 = 1*50) 

100 FORMAT (1015) 

DO 10 1=1*50 

I A R R A Y ( I ) = I A R R A Y ( I ) * 2 
10 CONTINUE 

C 

C Set an event flag to allow PAGEFIL1 to continue execution 

C 

STATUS = SYS$SETEF ( 7.0AL ( 73 ) ) 

IF (.NOT. STATUS) CALL LIB$STOP ( 7.U AL ( ST ATUS ) ) 

END 


Notes: 

O The $CRMPSC system service maps pages starting at page boundaries. Because 
all named COMMON blocks in FORTRAN are longword (not PAGE) aligned, you 
must ensure that IARRAY starts on a page boundary. The PSECT construct in the 
options file for the LINKER accomplishes this. PAGEFIL1 and PAGEFIL2 are 
linked with an options file. 

© Any variables or arrays that are used or modified by the AST routine should be 
declared VOLATILE in the other routines that reference them. See Section 1.3.2.2 
in this manual and Section 8.16 of Programming in VAX FORTRAN . 

© Associate to a common event flag cluster to coordinate activity. The processes must 
be in the same UIC group. 
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O The $CRMPSC system service creates and maps a global pagefile section. 

The starting and ending process virtual addresses of the section are placed in 
MY_ADR. The output argument SYS-ADR receives the starting and ending sys¬ 
tem virtual addresses. The flag SEC$M_GLOBAL requests a global section. The 
flag SEC$M_WRT indicates that the pages should be writable as well as readable. 
The SEC$M_DZRO flag requests pages filled with zeros. The SEC$M_PAGFIL 
flag requests a temporary pagefile section. 

© Data is written to the pagefile section. 

© PAGEFIL2 maps the existing section as writable by specifying the SEC$M_WRT 


flag. 


D.5 Sharing Code and Data 


The program called SHAREDFIL is used to update records in a relative file. The SHARE 
qualifier is specified on the OPEN statement to invoke the RMS file sharing facility. In this 
example, the same program is used to access the file from two processes. 

Source Program: 


c 

c 

c 

c 

c 

c 

c 


SHAREDFIL*FOR 


This program can be run from two or more processes 
to illustrate the use of an RMS shared file to share 
data* The program requires the existence of a 
relative file named R E L ♦ D A T ♦ 


IMPLICIT 

CHARACTER*20 

INCLUDE 


INTEGER*^ (A - Z) 

RECORD 

FORIOSDEF 


o 


c 


© 

© 


OPEN (UN IT =1 t FILE= 7 REL 7 , ST ATUS= 7 OLD 7 t SHARED t 
1 0RGANIZATI0N= 7 RELATI0E 7 t ACCESS= 7 DIRECT 7 » 

1 FORM = 7 FORMATTED 7 ) 


C 

C 

C 


Request record to be examined 


100 

10 


TYPE 10 

FORMAT ( 7 $Record number (CTRL Z to quit) 
READ i*i*t E N D =10 0 0) REC-NUM 


C 

C 

c 


Get record from file 


20 


READ (1 >20 > REC = REC_NUM t IOSTAT = STATUS) 
1 REC-LEN , RECORD 

FORMAT (Qf A) 
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c 

C ChecK I/O status 

C 

IF (STATUS .EQ. 0) THEN 

TYPE *» RECORD(1:REC_LEN) 0 

ELSE IF (STATUS .EQ♦ FOR$I0S_ATTACCNON) THEN 
TYPE * * 'Nonexistent record. 7 
GOTO 100 

ELSE IF (STATUS .EQ. FOR$IOS-RECNUMOUT) THEN 
TYPE * t 'Record number out of r a n S e ♦ ' 

GOTO 100 

ELSE IF (STATUS .EQ. FOR$IOS_SPERECLOC) THEN 

TYPE * t 'Record locked by someone else*' Q 
GOTO 100 

ELSE 

CALL ERRSNS <» RMS-STS» RMS_STO tt) 

CALL LIB$SI GNAL ( 7.0AL ( RMS_STS ) t 
1 7.0 A L ( R M S _ S T 0 ) ) 

END I F 
C 

C Request updated record 

C 

TYPE 30 

30 FORMAT ('$New Value or CR: ') 

READ (* »20) REC-LEN t RECORD 
IF (REC_LEN .NE* 0) THEN 

WRITE ilt40t REC = REC_NUM t IOSTAT = STATUS) 

1 RECORD(1:REC-LEN) 

HO FORMAT (A) 

IF (STATUS ♦NE♦ 0) THEN 

CALL ERRSNS <» RMS-STS , RMS-STO»») 

CALL LIB$SIGNAL(7.0AL(RMS-STS) »7.0AL ( RMS-STO ) ) 
END I F 
END I F 
C 

C Loop 

C 

GOTO 100 
C 

1000 END 

Sample Use: 

$ FORTRAN SHAREDFIL 
$ LINK SHAREDFIL 
$ RUN SHAREDFIL 


Record number (CTRL 

MSPIGGY 

2 

t 0 

quit) 

New Value or CR: F0 

2 2 

IE 


Record number (CTRL 

KERMIT 

New Value or CR: 

“7 

t 0 

quit) 

Record number (CTRL 

$ 

“7 

t 0 

quit) 
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$ RUN SHAREDFIL 

Record number (CTRL Z to quit); 2 O 
Record locked by someone else* 

Record number (CTRL Z to quit); 2 
Record locked by someone else* 

Record number (CTRL Z to quit): 2 
FOZZIE 

New Value or CR: MSPIGGY 

Record number (CTRL Z to quit): A Z © 

$ 

Notes: 

O The module FORIOSDEF must be included to define the symbolic status codes 
returned by FORTRAN I/O statements. 

© This program requires a relative file named REL.DAT. 

O The SHARED qualifier is used on the OPEN statement to indicate that the file can 
be shared. Because manual locking was not specified, RMS will automatically con¬ 
trol access to the file. Only read and update operations are allowed in this example. 
No new records may be written to the file. 

O The second process is not allowed to access record #2 while the first process is 
accessing it. 

® Once the first process has finished with record #2, the second process can update it. 


D.6 Gathering and Displaying Data at Terminals 


The following example calls SMG routines to format screen output. 

No sample run is included for this example because the program requires a video terminal 
to execute properly. 

Source Program: 


c 

c 

c 

c 

c 


SMGOUTPUT *FOR 


This program calls Run-Time Library Screen Management 
routines to format screen output* 


IMPLICIT INTEGERS (A-Z) 


INCLUDE 


($SMGDEF) 


o 


c 

c 

c 


Establish terminal screen as pasteboard 


STATUS = SMG$CREATE_PASTEBOARD (NEW_PID»,»> © 
IF (.NOT* STATUS) CALL LIB$STOP(ZVAL(STATUS) ) 
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c 

C Establish a virtual display region 

C 

STATUS = SMG$CREATE_UIRTUAL_DISPLAY (15 >30 #DISPLAY_ID » » # ) Q 
IF (.NOT* STATUS) CALL LIB$STOP<ZUAL<STATUS>> 

C 

C Paste the virtual display to the screen# starting at 

C row 5> column 15 

C 

STATUS = SMG$PASTE_UIRTUAL_DISPLAY(DISPLAY_ID#NEN_PID#2#15) Q 

IF (.NOT. STATUS) CALL LIB$STOP(ZUAL(STATUS)) 

C 

C Put a border around the display area 

C 

STATUS = SMG$LABEL_BORDER(DISPLAY_ID # 'This is the Border 7 #####) 0 

IF (.NOT. STATUS) CALL LI B$STO P ( 7.UAL < STATUS > ) 

C 

C Nrite text lines to the screen 

C 

STATUS = SMG$ PUT.LINE (DISPLAY_ I D# 7 7 #####) 

IF (.NOT. STATUS) CALL LI B$STOP ( /(.UAL ( STATUS ) ) 0 

STATUS = SMG$ PUT.LINE (DISPLAY.ID# 7 Howdy# pardner 7 #2»»»#) 

IF (.NOT. STATUS) CALL LIB$STOP(ZUAL(STATUS)) 

STATUS = SMG$ PUT.LINE (DISPLAY.ID # 'Double spaced 1 i nes . . ♦ 7 #2»#»#) 

IF (.NOT. STATUS) CALL LIB$STOP(ZVAL(STATUS)) 

STATUS = SMG$ PUT.LINE (DISPLAY_ID# 7 This line is blinking 7 #2# Q 

1 SMG$M_BLINK #0 # #) 

IF (.NOT. STATUS) CALL LIB$STOP(ZVAL(STATUS>> 

STATUS = SMG$ PUT.LINE (DI SPLAY.ID# 7 This line is reverse video 7 #2# 

1 SMG$M_REVERSE#0 # #) 

IF (.NOT. STATUS) CALL LIB$STOP(ZVAL(STATUS)) 

DO I = 1 # 5 

STATUS = SMG$PUT_LINE (DISPLAY_ID# 7 Sins1e spaced lines... 7 #####)© 
IF (.NOT. STATUS) CALL LIB$STOP(ZVAL(STATUS)) 

ENDDO 

C 

END 

Notes: 


O The INCLUDE statement incorporates the $SMGDEF module from FORSYS- 
DEF.TLB into the source program. This module contains symbol definitions used 
by the screen management routines. 

0 The call to SMG$CREATE_PASTEBOARD creates a pasteboard upon which out¬ 
put will be written. The pasteboard ID is returned in the variable NEW_PID. 

No value is specified for the output device parameter, so the output device defaults 
to SYS$OUTPUT. Also, no values are specified for the PB_ROWS or PB_COLS 
parameters, so the pasteboard is created with the default number of rows and col¬ 
umns. The defaults are the number of rows and the number of columns on the 
physical screen of the terminal to which SYS$OUTPUT is assigned. 
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0 The created virtual display is 15 lines long and 30 columns wide. The virtual dis¬ 
play initially contains blanks. 

Q The virtual display is pasted to the pasteboard, with it’s upper left corner posi¬ 
tioned at row 2, column 15 of the pasteboard. Pasting the virtual display to the 
pasteboard causes all data written to the virtual display to appear on the pas¬ 
teboard’s output device, which is SYS$OUTPUT —the terminal screen. 

At this point, nothing will appear on the terminal screen because the virtual dis¬ 
play contains only blanks. However, because the virtual display is pasted to the 
pasteboard, the program statements described below cause text to be written to 
the screen. 

0 A labeled border is written to the virtual display. 

® Text lines are written to the virtual display. The LINE_ADV parameter specifies 
double spacing. 

O These statements use the RENDITION_SET and RENDITION_COMPLEMENT 
parameters to display blinking and reverse video text. 

® Single spaced text is displayed. 


D.7 Creating, Accessing, and Ordering Files 


In the following example, each record in a relative file is assigned to a specific cell in that 
file. On sequential write operations, the records are written to consecutive empty cells. 
Random write operations place the records into cell numbers as provided by the REC = n 
parameter. 

Source Program: 

C RELATIVE.FOR 


C 

C 

C 

C 


This program illustrates accessing a relative file 
randomly. It also performs some I/O status checks. 


IMPLICIT 


INTEGER*^ (A - Z) 


STRUCTURE /EMPLOYEE_STRUC/ 


CHARACTER*!!} 
CHARACTER*G 
CHARACTER*3 
CHARACTER*2 
CHARACTER*^ 


NAME 

DEPT 

SKILL 


SALARY 


ID_NUM 


END STRUCTURE 

RECORD /EMPLOYEE-STRUC/ EMPLOYEE-REC 


INTEGER*^ 

INCLUDE 


REC-LEN 


($F0RIOSDEF) 


O 
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c 


OPEN (UN IT =1 t FILE = 7 PEL 7 t STATUS= 7 OLD 7 » © 

1 ORGANIZATION 13 'RELATIVE 7 * ACCESS = "DIRECT 7 t 

1 FORM = 7 UNFORMATTED 7 »RECORDTYPE= 7 VARIABLE 7 ) 

C 

C Get records by record number until e-o-f 

C Prompt for record number 

C 

100 TYPE 10 

10 FORMAT ( 7 $ R e c o r d number: 7 ) 

READ (*t*f E N D =10 0 0) REC_NUM © 

C 

C Read record by record number 

C 

READ (1»REC = REC-NUM#IOSTAT=STATUS) EMPLOYEE_REC 
C 

C ChecK I/O status 

C 

IF (STATUS ♦ EQ ♦ 0) THEN 

WRITE (G) EMPLOYEE-REC © 

ELSE IF (STATUS .EQ. FOR*I0S_ATTACCNON) THEN 
TYPE * t "Non existent record* 7 
ELSE IF (STATUS ♦EQ♦ FOR*IOS_RECNUMOUT) THEN 
TYPE * t 7 R e c o r d number out of r a n S e ♦ 7 

ELSE 

CALL ERRSNS (, RMS.STSt RMS.STV) © 

CALL L I B*S I GNAL ( 7 „VAL ( RMS.STS ) * 

1 7. V A L ( R M S _ S T V ) ) 

END I F 
C 

C Loop 

C 

GOTO 100 
1000 END 

Sample Use: 

* FORTRAN RELATIVE 

* LINK RELATIVE 

* RUN RELATIVE 
Record number: 7 
08001FLANJE119PL1920 
Record number: 1 

0 7 G 7 2 A L B E H A 2 1 0 S E 2 1 0 0 
Record number: 30 
Nonexistent record* 

Record number: A Z 

* 

Notes: 

O The INCLUDE statement defines all FORTRAN I/O status codes. 
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Q The OPEN statement defines the file and record processing characteristics. 
Although a file organization of relative is specified, RMS would in fact obtain the 
file organization from an existing file. If the file’s organization were not relative, 
the file open statement would fail. 

The file is being opened for unformatted I/O because the data records will be read 
into a FORTRAN RECORD (EMPLOYEE_REC), and FORTRAN does not allow 
records to be used in formatted I/O. 

Q The READ statement reads the record specified in REC_NUM, rather than the 
next consecutive record. The status code for the record operation is returned in the 
variable STATUS. 

O These statements test the record operation status obtained in comment 3. Note, 
the status codes returned by VAX RMS and VAX FORTRAN are not numerically 
or functionally similar. 

G VAX RMS status codes actually require two parameters. These values can be 
obtained using the ERRSNS subroutine. 


D.8 Measuring and Improving Performance 


This example illustrates how to adjust the size of the process working set from a program. 

Source Program: 


c 

c 

c 

c 

c 


ADJUST♦FOR 


This program illustrates how a program can control 
its working set size u s i n S the $ A D J N S L system service 


IMPLICIT 

INCLUDE 

INTEGER*^ 

INTEGER*^ 


INTEGER (A-Z) 
7 <$SYSSRONAM) 
ADJUST_AMT 
NEW-LIMIT 


/0/ 

/0/ 


C 


DO 100 ADJUST-AMT = -50,70*10 


C 

C 

C 


Modify working set limit 


RESULT = SYS$ADJWSL( 7.0AL( AD JUST-AMT) , NEM.LIMIT) 
IF ( ♦ NOT ♦ RESULT) CALL L I B$ST0 P ( 7,0 AL ( RESULT)) 


o 


c 


50 


100 

C 


TYPE 50, ADJUST_AMT, NEN-LIMIT 
F 0 R M A T( 7 Modify working set by 7 , I 4 > 

1 7 New work ins set size = 7 , 14) 

CONTINUE 


END 
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Sample Use: 


$ SET WORKING-SET/NOADJUST © 

$ SHOW WORKING-SET 


Working Set /L i m i t = 150 /Q uo t a = 200 /E x t e n t = 

Adjustment disabled Authorized 0uo t a = 200 Authorized Extent 3 


$ FORTRAN ADJUST 
$ LINK ADJUST 
$ RUN ADJUST 


Modify 

wo rking 

set 

by 

-50 

New 

wo rkinS 

set 

size 

= 

100 

Modify 

w orkinS 

set 

by 

-40 

N e w 

w o r k i n g 

set 

size 

= 

GO 

Modify 

w orkins 

set 

b y 

-30 

New 

w o r k i n g 

set 

size 

= 

41 

Modify 

w o r k i n g 

set 

by 

-20 

N e w 

wo rkins 

set 

size 

= 

41 

Modify 

w o r k i n s 

set 

b y 

-10 

New 

wo rkin 3 

set 

size 

= 

41 

Modify 

wo rkins 

set 

b y 

0 

N e w 

w o r k i n g 

set 

size 

= 

41 

Modify 

w o r K i n g 

set 

by 

10 

N e w 

w o r k i n g 

set 

size 

= 

51 

Modify 

wo rkin g 

set 

b y 

20 

N e w 

wo rkin S 

set 

size 

= 

71 

Modify 

w o r k i n g 

set 

b y 

30 

N e w 

w o r k i n g 

set 

size 

= 

101 

Modify 

w o r k i n g 

set 

b y 

40 

N e w 

w o rking 

set 

size 

= 

141 

Modify 

w o r k i n g 

set 

b y 

50 

N e w 

w o r k i n g 

set 

size 

= 

191 

Modify 

w o r k i n g 

set 

b y 

GO 

N e w 

wo rking 

set 

size 

= 

200 

Modify 

w o r k i n g 

set 

b y 

70 

New 

w o rking 

set 

size 

= 

2 0 0 


Notes: 


o 


o 


200 


200 


Q The SYS$ADJWSL is used to increase or decrease the number of pages in the pro¬ 
cess working set. 

© The DCL SHOW WORKING-SET command displays the current working set 
limit and the maximum quota. 

© Notice that the program cannot decrease the working set limit beneath the mini¬ 
mum established by the operating system. 

© Similarly, the process working set cannot be expanded beyond the authorized 
quota. 


D.9 Accessing Help Libraries 

The following example illustrates how to obtain text from a help library. After the initial 
help request has been satisfied, the user is prompted and can request additional 
information. 

Source Program: 

C HELPOUT♦FOR 

C 

C This program satisfies an initial help request 

C and enters interactive HELP mode* The library 

C used is SYS$HELP:HELPLIB♦HLB♦ 

C 

IMPLICIT INTEGER*^ (A - Z) 

CHARACTER*32 KEY 

EXTERNAL LIB$PUT-OUTPUT »LIB$GET_INPUT © 
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Request a HELP Key 


C 
C 
C 

WRITE (G »2 0 0 0 ) 

2000 FORMAT*IX»'What Topic would you like HELP with? ' > $ ) 
READ (5»1000) KEY 
1000 FORMAT (A32) 

C 

C Locate and print the help text 

C 

STATUS = LBR$OUTPUT_HELP(LIB$PUT_OUTPUT t >KEY * Q 

1 ' HEL PL IB ' t »LIB$GET_INPUT) 

IF (.NOT* STATUS) CALL LIB$STOP ('/.UAL (STATUS) ) 

END 

Sample Use: 

$ FORTRAN HELPOUT 
$ LINK HELPOUT 
$ RUN HELPOUT 

What topic would you like HELP with? TYPE 
TYPE 


Displays the contents of a file or a Sroup of files on the 
current output device. 


F o rinat : 

TYPE file-spect ».. ♦ ] 

Additional information available: 

Parameters Qualifiers 
/OUTPUT 

TYPE Subtopic? /OUTPUT 
TYPE 


/OUTPUT 

/OUTPUT = fi1 e-spec 

Requests that the output from the TYPE command be written 
to the specific file* rather than to SYS$OUTPUT. 

TYPE Subtopic? A Z 
$ 

Notes: 

O To pass the address of LIB$PUT_OUTPUT and LIB$GET_INPUT, they must be 
declared as EXTERNAL. You may supply your own input and/or output routines. 
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0 The address of an output routine is a required argument. When requesting 
prompting mode, the default mode, an input routine must be specified. 


D.10 Creating and Managing Other Processes 

The following example illustrates the ability of a created process to use the 
SYS$GETJPIW system service to obtain the PID of its creator process. 


Source Program: 


c 

c 

c 

c 

c 


c 

c 

c 

c 


c 

c 

c 

1 00 


GET JPI♦FOR 

This program illustrates process creation and 
control. It creates a sub process then hibernates 
until the subprocess wakes it* 


IMPLICIT 

INTEGERS (A - Z) 

i 

INCLUDE 

7 ($SSDEF ) 7 


INCLUDE 

7 ($LNMDEF ) 7 


INCLUDE 

7 ( $ S Y S S R 0 N A M ) 7 


CHARACTER*255 

TERMINAL 

/ 7 SYS$OUTPUT 7 / 

CHARACTER*9 

FILE-NAME 

/ 7 GET J PI SUB 7 / 

CHARACTERS 

SUB-NAME 

/ 7 OSCAR 7 / 

INTEGERS 

PROCESS-ID 

/O/ 

CHARACTER*17 

TABNAM 

/ 7 LNM$PROCESS-TABLE 7 / 

CHARACTER*255 

RET-STRING 


CHARACTER*2 

ESC-NULL 


INTEGERS 

RET-ATTRIB 


INTEGERS 

RET-LENGTH 

/ 1 0 / 

INTEGER*2 

TRNLST(20) 

/a* LNM$_STRING » 4 * 0 * 

1 


at LNM$_ATTRIBUTES 

1 


4* LNM$_LENGTH »G*0 

BYTE 

ESC_NULL_NUM(2: 

» / 7 1 B 7 X » 7 00 7 X/ 


EQUIOALENCE (ESC-NULL* ESC_NULL_NUM) 

Translate SYS$OUTPUT 

Set up TRNLST* the item list for $TRNLNM 

TRNLST(1) = 255 

TRNLST ( 3 ) = 7.L0C(RET_STRING) 

TRNLST(7) = a 

TRNLST ( 3 ) = 7.L0C(RET_ATTRIB) 

TRNLST(13) = a 

TRNLST ( 15) = 7.L0C(RET_LENGTH) 

Translate SYS$OUTPUT 

STATUS = SYS$TRNLNM <>TABNAM*TERM INAL(1:RET_LENGTH )tt TRNLST) 
IF (.NOT. STATUS) CALL LIB$STOP (7.0AL (STATUS) ) 

IF (IAND(LNM$M_TERMINAL t RET_ATTRIB) .EQ. 0) THEN 
TERMINAL = RET-STRING<1:RET-LENGTH) 

GO TO 100 

END I F 
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n n 



10 

C 

C 

C 


C 


Check if process permanent file 

IF <RET_STRING(1:2> .EQ. ESC.NULL) THEN 

RET-STRING = RET_STRING(5:RET_LENGTH) 
RET_LENGTH = RET-LENGTH - 4 

END I F 


Create the sub process 

STATUS = SYS$CREPRC (PROCESS-ID, FILE-NAME * t 
1 RET_STRING(1:RET-LENGTH) » , , , 

1 SUB-NAME tXV AL<4) t t t) 

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS)) 
TYPE 10» PROCESS-ID 

FORMAT < 7 PID of subprocess OSCAR is ' t Z) 

Wait for wakeup by subprocess 
STATUS = SYS$HIBER () 

IF (.NOT. STATUS) CALL LIB$STOP (’/.UAL (STATUS) ) 

TYPE * * 7 G E T J PI has been awakened♦ ' 

END 


o 


e 



c 

c 

c 


c 


c 

c 

c 



c 


GETJPISUB.FOR 

This program is run in the sub process OSCAR 
which is created by GETJPI. It obtains its 
creator's PID and then wakes it. 

Q 


O 

Set up buffer address for GETJPI 


IMPLICIT INTEGER*4 (A - 2) 

INCLUDE 7 ($J PIDEF) 7 

INCLUDE 7 ($ S Y S S R 0 N A M) 7 

INTEGER*2 I0SB<4) 

INTEGER*2 JPI_LIST<8) /4> JPI$_OWNER, G*0/ 

EQUIVALENCE (JPI_LIST(3) * OWNER-PID_ADDR) 


OWNER-PID-ADDR = ZLOC(OWNER.PID) 

Get PID of creator 

STATUS = SYS$GET JPIW (ZVAL(1)»»# JPI_LI ST »IOSB * *) © 

IF (.NOT. STATUS) CALL LIB$STOP (!^OAL (STATUS) ) 

IF (.NOT. I OSB(1) ) CALL LIB$STOP (XVAL(IOSB(1) ) ) 


Wake creator 


TYPE * » 7 OSCAR is 

STATUS = S Y S $ W A K E 
IF (.NOT. STATUS) 


waking creator. 7 
(OWNER-PID >) 

CALL LIB$STOP ( 7JJ AL ( STATUS ) ) 


END 
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Sample Use: 

$ FORTRAN GETJPItGETJPISUB 
$ LINK GETJPI 
$ LINK GET JPI SUB 
$ RUN GET JPI 

PID of sub process OSCAR is 530048 
OSCAR is waKins creator* 

G E T J PI has been awakened* 

Notes: 

O The subprocess is created using SYS$CREPRC. 

Q The process hibernates. 

Q The INCLUDE statement defines the value of all JPI$ codes including 
JPI$_OWNER. JPI$_OWNER is the item code which requests the PID of the 
owner process. If there is no owner process (that is, if the process about which infor¬ 
mation is requested is a detached process), the system service $GETJPIW returns 
a PID of zero. 

O Because of the item code JPI$_OWNER in the item list, $GETJPIW returns the 
PID of the owner of the process about which information is requested. If the item 
code were JPI$_PID, $GETJPIW would return the PID of the process about which 
information is requested. 

Because the default value of 0 is used for arguments PID ADR and PRCNAM, the 
process about which information is requested is the requesting process, namely, 
OSCAR. 

Q The item list for SYS$GETJPIW consists of a single item descriptor followed by a 
zero longword. 
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Index 


A 

Actual arguments 
see arguments, actual and dummy 
Algorithms 

affect on run-time performance, 1-2 
to 1-3 

Allocation control block 
XABALL, 4-13 
Allocation of disk space 
SYS$EXTEND, 4-20 
Arguments, actual and dummy 
VAX FORTRAN implementation 

of argument association, 2-7 to 2-8 
declaring argument addresses as 
VOLATILE, 1-8 
Argument lists 

argument list built-in functions 
examples of 3-14 to 3-15 
%VAL, %REF, %DESCR, 3-2 to 3-3 
character function argument lists 
example of, 3-15 

source and object code examples, 3-12 
to 3-14 

VAX conventions, 3-1 to 3-2 
Argument passing 

by immediate value, reference, and 
descriptor methods, 3-2, 3-7 to 3-9 
by data structure method, 3-9 to 3-10 
examples of, 3-10 to 3-15 
RMS arguments, 4-16 
Arrays 

global analysis optimizations, 1-6 to 1-10 
VOLATILE effects, 1-7, 1-8 
large array referencing techniques 

to avoid page faulting, 1-24 to 1-25 
use of in loops 

to promote optimizations, 1-23 to 1-24 


ASSIGN subroutine 
PDP-11 compatible, B-6 to B-7 
AST procedures 
example of use, D-3 to D-4 
Asynchronous trap procedures 
see AST procedures 

B 

BACKSPACE statement 
avoiding use of, 1-29 
$BLANK program section 
use and attributes, 2-2 
BLANK keyword (OPEN) 
defaults 

FORTRAN-66 vs. FORTRAN-77, A-3 to 
A-4 

BYTE data type 
see LOGICAL*! 


c 

Call conventions, VAX 
argument lists, 3-1 to 3-2 
argument-passing mechanisms, 3-2 to 3-4 
external procedure return values, 3-4 
Character and Hollerith constants 
VAX FORTRAN vs. PDP-11 FORTRAN, 
B-2 to B-3 

Character function argument lists 
example of, 3-15 
Close operations 
closing a file using RMS, 4-18 
DISPOSE=‘PRINT’ 

VAX FORTRAN vs. PDP-11 FORTRAN, 

B-3 
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Close operations, (Cont.) 
error reporting 

VAX FORTRAN vs. PDP-11 FORTRAN, 
B-5 

CLOSE subroutine 
PDP-11 compatible, B-7 
$CODE program section 
use and attributes, 2-2 
Coding practices 

affecting performance optimizations 
see optimization techniques (user) 

COM files 

used in network task-to-task 
communications, 5-9, 5-10 
Common areas, installed, 5-2 
creation, installation, and use, 5-3 to 5-4 
synchronizing access to, 5-4 
Communications, network task-to-task, 5-8 
to 5-10 

Compiler optimization techniques 
see optimization techniques 
Condition handlers 
definition of, 6-2 
avoiding optimization problems 

by declaring variables as VOLATILE, 
1-8 

condition values and symbols, 3-5, 6-8 
to 6-10 

default handler, 6-3 
dummy arguments for, 6-5 to 6-7 
establishing handler, 6-2, 6-5 
examples of use, 6-14 to 6-19 
function return values, 6-7 to 6-8 
handler responses, 6-4 to 6-5 
removing handler, 6-5 
resignaling handler, 6-3 
signaling handler, 6-2, 6-3 to 6-4 
unwinding procedure activation, 6-3 
Condition symbols 
definiton of, 6-2 

FORSYSDEF modules containing symbols, 
6-10 

Condition values 

used by error recovery procs, 3-5, 6-8 
to 6-10 

Connected units 
attempting open operations on 

FORTRAN-77 vs. FORTRAN-66, A-5 


Conversions 

smaller to larger fixed-point data types, 2-5 

D_and G_floating data, 2-11 to 2-13 

CTRL/C trapping 
SYS$QIOW example, 3-11 to 3-12 



D 

Data 

sharing 

in files, 5-4 to 5-5, D-9 to D-ll 
in installed common areas, 5-2 to 5-4 
in shareable images, 5-1 to 5-2 
exchanging 

using mailboxes (SYS$CREMBX), 5-5 to 5-7 
using network task-to-task 

communications, 5-8 to 5-10 
Data structures 

argument passing mechanism, 3-9 to 3-10 
see also RMS data structures 
Data types 

conversion techniques and intrinsic 
functions for, 2-5 
effect on function returns, 3-4 
types of address arguments required, 3-9 
Date and time control block 
XABDAT, 4-13 

see also revision date and time control block 
Dead store elimination 
optimization technique, 1-16 to 1-17 
Debugging 

affect of optimizations on, 1-4 to 1-6 
DECnet-VAX 
using to share and exchange data, 5-8 to 5-10 
%DESCR 

argument list built-in function 

for passing arguments to nonFORTRAN 
procs, 3-2, 3-3 
example of, 3-15 
Descriptor 

argument passing mechanism, 3-2 

D_floating data implementation, 2-11 

Diagnostic messages 
affect of optimizations on, 1-3 to 1-4 
Directory entries 
system services affecting 
list of, 4-19 to 4-20 
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Disk space allocation 
SYS$EXTEND, 4-20 
DO loops 

minimum iteration counts 
FORTRAN-77 vs. FORTRAN-66, A-2 
VAX FORTRAN implementation, 2-5 to 
2-7 

Dummy arguments 
see arguments 


E 

ENTRY statements 
VAX FORTRAN implementation 
of argument association, 2-7 to 2-8 
EQUIVALENCE statements 
affect on optimization, 1-7 
Errors 

continuation after errors 
VAX FORTRAN vs. PDP-11 FORTRAN, 
B-4 to B-5 
Error numbers 

common error numbers (IOSTAT values), 
6-10 

FORSYSDEF modules containing symbols 
for, 6-10 

PDP-11 run-time error number differences, 
B-4 

Error recovery procedures 
use of condition codes, 3-5 
ERRSET subroutine 
PDP-11 compatible, B-7 to B-8 
ERRSNS subroutine 
example of use, D-10, D-14 
PDP-11 run-time error number differences, 
B-4 

ERRTST subroutine 
PDP-11 compatible, B-8 to B-9 
ESA, 4-24 
Event handling 
see condition handlers 
Exception conditions 
definition of 6-2 
see also condition handlers 
Expanded string area 
see ESA 


Extended access block 
see XAB 

External procedures 
method of returning values, 3-4 
EXTERNAL statement 
FORTRAN-77 vs. FORTRAN-66, A-2 to 
A-3 

F 

FAB 

symbol naming conventions, 4-3 to 4-5 
fields initialized 

as result of USEROPEN, 4-25 to 4-28 
general description, 4-5 to 4-7 
overview, 4-2 
FABDEF module 
in FORSYSDEF, 4-6 
Faults and traps 

floating reserved operand faults, 6-12 
method of signaling condition handlers, 
6-11 to 6-12 

overriding default fault handling 

LIB$DECODE_FAULT, 6-14 

FDBSET subroutine 
PDP-11 compatible, B-9 to B-10 
File access, remote, 5-8 
File access block 
see FAB 
File handling 

creating, accessing, and ordering 
examples of, D-13 to D-15 
File header characteristics 
control block for 
XABFHC, 4-13 
File processing, I/O related 
closing a file using RMS, 4-18 
opening a file using RMS, 4-18 
other file processing services 
list of, 4-19 to 4-20 
File sharing 

accessing remote files, 5-8 
RMS file-sharing capability, 5-4 to 5-5 
example of, D-9 to D-ll 
shareable image libraries, 5-1 to 5-2 
Fixed point data types 
storage allocations of, 2-3 to 2-5 
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Floating-point data 
computation accuracy 
VAX FORTRAN vs. PDP-11 FORTRAN, 
B-2 

VAX FORTRAN programming restrictions, 
2-9 to 2-10 

G_vs. D_floating implementations, 2-10 

to 2-13 

Floating-point errors 
floating reserved operand faults, 6-12 
Floating underflow 
default processing, 6-13 
user-selected options, 6-13 to 6-14 

FOR$UNDERFLOW_HANDLER, 6-13, 

6-14 

$FORDEF, 6-10 
Formatted I/O 
see I/O operations 

FORSYSDEF — FORTRAN symbolic 
definitions 

complete list of FORTRAN modules in, C-l 
to C-6 

condition handler modules 
$FORDEF, $LIBDEF, $MTHDEF, 
$SSDEF, 6-10 
description of, 3-5 to 3-6 
description of symbol naming conventions, 
4-3 to 4-5 

use with RMS data structures, 4-2, 4-3 
FABDEF module, 4-6 
NAMDEF module, 4-11 
RABDEF module, 4-8 
FORTRAN 
see VAX FORTRAN 
FORTRAN-66 

differences with FORTRAN-77, A-l, A-2 
to A-5 

use of /NOF77 qualifier 
FORTRAN-77, VAX implementation of 
data type conversion, 2-5 
differences with FORTRAN-66, A-l to A-5 
differences with PDP-11 FORTRAN IV, 
B-l to B-5 

differences with PDP-11 FORTRAN-77, 
B-l to B-5 
DO loops, 2-5 to 2-7 

ENTRY statement arguments, 2-7 to 2-8 
floating-point data, 2-8 to 2-13 
integer and LOGICAL* 1 data types, 2-4 to 
2-5 


FORTRAN-77, VAX implementation, (Cont.) 
PSECT use and attributes, 2-1 to 2-2 
storage allocation, 2-3 to 2-5 
Function codes 
use as input arguments 
to system services, 3-5 
Function names 
assigning values to, 3-4 
Function references 
avoiding optimization problems with 
in logical expressions, 1-13 
use to call system services, 3-6 
Function return values 
from condition handlers, 6-7 to 6-8 
return mechanisms, 3-4 
Function subprograms 
definition of, 3-4 

G 

G_floating data implementation, 2-10 to 

2-13 

Global analysis optimizations, 1-6 to 1-10 
effect on speed optimizations, 1-10 to 1-11 
Global pagefile section 
use of, D-6 to D-9 


H 

Help libraries 
obtaining text from 
example of, D-16 to D-18 
Hollerith and character constants 
VAX FORTRAN vs. PDP-11 FORTRAN, 
B-2 to B-3 


I 

IF statements 

compound logical expressions in 
optimizations performed on, 1-12 to 1-13 
Immediate value 

argument passing mechanism, 3-2, 3-7 
INSTALL command (DCL) 
use to install shareable images, 5-1, 5-2 
Installed common areas, 5-2 
creation, installation, and use, 5-3 to 5-4 
synchronizing access to, 5-4 
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Integer data types 
integer constant typing, 2-3 to 2-4 
relationship of *2 and *4 values, 2-3 
Intrinsic functions 
for converting data types, 2-5 
I/O operations 
block mode I/O 
example of, 4-30 to 4-36 
formatted vs. unformatted, 1-27 to 1-29 
reading data using RMS, 4-19 
record processing RMS services 
list of, 4-20 

writing data using RMS, 4-18 to 4-19 
see also file processing, terminal I/O 
I/O optimizations 
user options, 1-27 to 1-33 
use of variable format expressions, 1-10 
IOSTAT values, 6-10 
IRAD50 subroutine 
PDP-11 compatible, B-10 
IZEXT intrinsic function 
data type conversion, 2-5 

j 

Journaling control block 
XABKEY, 4-13 
JZEXT intrinsic function 
data type conversion, 2-5 

K 

Key definition control block 
XABKEY, 4-13 

L 

$LIBDEF, 6-10 

LIB$DATE_TIME 

example of use, D-4 

LIB$DECODE_FAULT, 6-14 

LIB$ESTABLISH, 6-2, 6-5 
example of use, 6-15, 6-16, 6-17 

LIB$FIXUP_FLT, 6-12 

LIB$FLT_UNDER, 6-14 

LIB$GET_INPUT 

example of use, D-16 to D-17 

LIB$MATCH_COND 

example of use, 6-15 


LIB$PUT_O UTPUT 

example of use, D-16 to D-17 
LIB$REVERT, 6-5 

LIB$SIM_TRAP, 6-12 

LIB$SIGNAL 
definition of, 6-2 
example of use, 4-17, D-10, D-14 
general description of, 6-3 to 6-4 
LIB$STOP 
definition of 6-2 
example of use, 4-17, D-5 
general description of, 6-3 to 6-4 
%LOC built-in function 
for passing arguments to nonFORTRAN 
procs, 3-2, 3-4 
Local processes 

exchanging and sharing data between, 5-1 
to 5-10 

$LOCAL program section 
use and attributes, 2-2 
Logical I/O units 

attempting opens on connected units 
FORTRAN-77 vs. FORTRAN-66 
behaviors, A-5 
default numbers 

VAX FORTRAN vs. PDP-11 FORTRAN, 

B-3 

Logical expressions 
in function references 
avoiding optimization problems with, 
1-13 

LOGICAL* 1 data type 
treatment of, 2-5 
Loops 

see DO loops 


M 

Mailboxes 

SYS$CREMBX, 5-5 to 5-7 
MECHARGS 
description of, 6-6 to 6-7 
Memory usage 

compiler optimization techniques, 1-33 to 
1-34 
Messages 

see diagnostic messages 
$MTHDEF, 6-10 
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N 

NAM, 4-2 

description of symbol naming conventions, 
4-3 to 4-5 

general description of use, 4-11 to 4-13 
NAMDEF module 
in FORSYSDEF, 4-11 
Name block 
see NAM 

Networking environments 
sharing and exchanging data in, 5-8 to 5-10 
/NOOPTIMIZE qualifier 
when to use, 1-4 to 1-5 

o 

Open operations 

attempting an open on connected unit 
FORTRAN-77 vs. FORTRAN-66 
behaviors, A-5 
error reporting 

VAX FORTRAN vs. PDP-11 FORTRAN 
behaviors, B-5 

opening a file using RMS, 4-18 
Open procedures, user-written 
see USEROPEN routines 
OPEN statement 
DISPOSE=‘PRINT’ 

VAX FORTRAN vs. PDP-11 FORTRAN 
behaviors, B-3 

file-sharing parameters, 5-4 to 5-5 
keyword defaults 

FORTRAN-77 vs. FORTRAN-66, A-3 to 
A-4 

keywords pertaining to I/O, 1-28, 1-29 to 
1-30 

use with USEROPEN routines, 4-1, 4-25 to 
4-29 

example of, 4-30, 4-31 
Optimization techniques, compiler 

code removal optimizations, 1-11 to 1-17 
compile-time operations, 1-11 to 1-12 
code replacement optimizations, 1-17 to 
1-25 

use of registers by compiler, 1-22 to 1-23 
global analysis optimizations, 1-6 to 1-10 
I/O optimizations, 1-27 to 1-33 
operation specific optimizations, 1-25 to 
1-27 


Optimization techniques, user 
adjustments to process working set 
example of, D-15 to D-16 
autoincrement/autodecrement address 
modes 

coding practices that enable, 1-20 to 1-21 
BACKSPACE statements 
avoiding use of, 1-29 
EQUIVALENCE statements 
avoiding unnecessary use, 1-7 
function references 
in logical expressions, 1-13 
I/O optimizations, 1-27 to 1-33 
loop optimizations 

block moves/initializations within, 1-23 to 
1-24 

use of arrays within, 1-23 to 1-24 
page faults 

coding practices to reduce, 1-24 to 1-25 
shared global common 
declaring variables as VOLATILE, 1-8 
statement functions 
promoting inline expansion of, 1-9 
user-developed algorithms 
impact of, 1-2 to 1-3 
variable format expressions 
restricting use of variables in, 1-10 
Optimized programs 
optimized vs. unoptimized, 1-3 to 1-4 
effect on debugging, 1-4 to 1-6 
effect on diagnostics, 1-3 to 1-4 
use of VOLATILE 
to disable optimizations, 1-7 


Page faults 

coding practices to reduce, 1-24 to 1-25 
$PDATA program section 
use and attributes, 2-2 
PDP-11 FORTRAN 

differences with VAX FORTRAN, B-l to 
B-5 

subroutines supported by VAX FORTRAN 
for compatibility purposes, B-5 to B-13 
Performance optimization 
definition, 1-1 

see also optimization techniques, compiler; 
optimization techniques, user 
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Procedures 

definition of, 3-4, 6-2 
Procedure activation 
definition of, 6-2 

Procedure-calling conventions, VAX 
argument lists, 3-1 to 3-2 
argument-passing mechanisms, 3-2 to 3-4 
external procedure return values, 3-4 
Processes 
local 

exchanging and sharing data between, 5-1 
to 5-7, D-6 to D-9 
remote 

exchanging and sharing data between, 5-7 
to 5-10 

Process working set 

example of how to adjust, D-15 to D-16 
Program sections 
use and attributes of, 2-1 to 2-2 
Protection control block 
XABPRO, 4-13 
PSECTs 

see program sections 

Q 

QIO services, 1-31 
see also SYS$QIOW 

R 

RAB, 4-2 

description of symbol naming conventions, 
4-3 to 4-5 
fields initialized 

as a result of USEROPEN, 4-28 to 4-29 
general description of use, 4-7 to 4-11 
use by USEROPEN 
to access RMS control structures, 4-24 
RABDEF module 
in FORSYSDEF, 4-8 
RAD50 function subprogram 
PDP-11 compatible, B-ll 
RAN function subprogram 
PDP-11 compatible, B-ll 
RANDU subroutine 
PDP-11 compatible, B-12 
R50ASC subroutine 
PDP-11 compatible, B-12 to B-13 


Read operations 
see I/O operations 
Record access block 
see RAB 
Record I/O 
see I/O operations 
Record locking 
RMS facility for, 5-5 
Record Management Services, VAX 
see RMS 

RECORD statement 
use to declare RMS control blocks, 4-2 
%REF 

argument list built-in function 
for passing arguments to nonFORTRAN 
procs, 3-2, 3-3 
example of, 3-14 
Reference 

argument passing mechanism, 3-2, 3-8 to 

3- 9 

Remote file access, 5-8 
Remote processes 

exchanging and sharing data between, 5-8 
to 5-10 

Resultant string area 
see RSA 

Return status values 
use of system symbols, 3-5 to 3-6 
checking after function reference call, 3-6 
RMS example, 4-16 to 4-17 
Revision date and time control block 
XABRDT, 4-13 

see also date and time control block 
RMS 

data structures (FAB, RAB, NAM, XAB), 

4- 2, 4-24 
FAB, 4-5 to 4-7 
RAB, 4-7 to 4-11 

affect of USEROPEN routines, 4-1 to 
4-2, 4-24 

method of accessing from USEROPEN, 
4-24 

steps to using, 4-2 to 4-3 
example of call to RMS, D-l to D-2 
file sharing capability, 5-4 to 5-5 
example of, D-9 to D-ll 
I/O optimizations, 1-30 to 1-31 
overview of how to use RMS services, 4-15 
to 4-20 
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RMS, (Cont.) 
record locking facility, 5-5 
see also VAX/VMS system services 
RMSDEF, 4-16 
RSA, 4-24 
RTL 

data conversion functions, 2-11 to 
2-12 

data conversion subroutines, 2-11, 2-12 to 
2-13 

FORTRAN I/O support routines 
used as result of USEROPEN, 4-1 
procedures 

see index entries for LIB$xxxxx 
RMS control structures 
constructed as result of USEROPEN, 
4-1, 4-24 

Run-time error numbers 
VAX FORTRAN vs. PDP-11 FORTRAN, 
B-4 

Run-Time Library 
see RTL 

Run-time performance 
affect of user-developed algorithms, 1-2 to 
1-3 

s 

Screen management subroutines 
examples of use, D-ll to D-13 
Shareable image libraries 
benefits, 5-1 

creating and installing, 5-2 
Shared files, 5-4 to 5-5 
Shared global common 
declaring variables as VOLATILE, 1-8 
Sharing data 
see data sharing 
SIGARGS 
description of, 6-6 
Signaling operation 
definition of, 6-2 
SMG routines 

examples of use, D-ll to D-13 

SMG$CREATE_PASTEBOARD 

example of use, D-ll 

S M G$CRE ATE_VIRTUAL_TERMIN AL 

example of use D-12 


SMG$LABEL_BORDER 

example of use, D-12 

SMG$PASTE_VIRTUAL_DISPLAY 

example of use, D-12 

SMG$PUT_LINE 

example of use, D-12 
Source program optimizations 
affects of user-developed algorithms 
on run-time performance, 1-2 to 1-3 
Statement functions 

inline expansion optimization, 1-8 to 1-9 
STATUS keyword (OPEN) 
defaults for FORTRAN-77 vs. 

FORTRAN-66, A-4 
Status values 
see return status values 
Storage allocation 

of fixed point data types, 2-3 to 2-5 
Subexpression elimination optimization, 
1-13 

Subprograms 

methods of returning values from, 3-4 
Subroutines 

calling system services as subroutines 
effect of, 3-7 
Summary control block 
XABSUM, 4-13 
System services 
see VAX/VMS system services 
SYS$ADJWSL 
example of use, D-15 
SYS$ASCEFC 
example of use, D-7, D-8 
SYS$ASSIGN 
example of use, D-5, D-6 
SYS$BINTIM 
example of use, D-3, D-4 
SYS$CLOSE, 4-18 

data structure needed to use, 4-5 to 4-7 
SYS$CONNECT 

data structure needed to use, 4-7 to 4-11 
use to open a file, 4-18 
example of, 4-32, 4-33 
SYS$CREATE 

data structure needed to use, 4-5 to 4-7 
use to open a file, 4-18 
example of, 4-32 
SYS$CREMBX, 5-5 to 5-7 
example of use, 5-7 
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SYS$CREPRC 
example of use, D-19 
SYS$CRMPSC 
example of use, D-7 
SYS$DELETE, 4-20 
data structure needed to use, 4-7 to 4-11 
SYS$DISCONNECT, 4-18 
data structure needed to use, 4-7 to 4-11 
SYS$DISPLAY, 4-19 
data structure needed to use, 4-5 to 4-7 
SYS$ENTER, 4-20 

data structure needed to use, 4-5 to 4-7 
SYS$ERASE, 4-20 

data structure needed to use, 4-5 to 4-7 
SYS$EXTEND, 4-20 
data structure needed to use, 4-5 to 4-7 
SYS$FIND, 4-20 

data structure needed to use, 4-7 to 4-11 
SYS$FLUSH 

data structure needed to use, 4-7 to 4-11 
SYS$FREE 

data structure needed to use, 4-7 to 4-11 
SYS$GET, 4-19 

data structure needed to use, 4-7 to 4-11 
SYS$GETJPI, 3-10 to 3-11 
SYS$GETJPIW 
example of use, D-18 to D-20 
SYS$GETMSG 
example of use, 6-18 
SYS$HIBER 
example of use, D-19 
SYS$MGBLSC 
example of use, D-8 
SYS$NXTVOL 

data structure needed to use, 4-7 to 4-11 
SYS$OPEN 

data structure needed to use, 4-5 to 4-7 
example of use, 4-17, 4-33 
when to use, 4-18 
SYS$PARSE, 4-19 

data structure needed to use, 4-5 to 4-7 
SYS$PUT, 4-18 to 4-19 
data structure needed to use, 4-7 to 4-11 
SYS$QIOW, 3-11 to 3-12 
example of use, 6-18, D-5 to D-6 
see also QIO 
SYS$READ, 4-19 

data structure needed to use, 4-7 to 4-11 
example of use, 4-35 


SYS$RELEASE 

data structure needed to use, 4-7 to 4-11 
SYS$REMOVE, 4-20 
data structure needed to use, 4-5 to 4-7 
SYS$RENAME, 4-20 
data structure needed to use, 4-5 to 4-7 
data structure needed to use, 4-7 to 4-11 
SYS$REWIND 

data structure needed to use, 4-7 to 4-11 
SYS$SEARCH, 4-19 
data structure needed to use, 4-5 to 4-7 
SYS$SETDDIR 
example of use, D-2 
SYS$SETEF 
example of use, D-7, D-8 
SYS$SETIMR 
example of use, D-3, D-4 
SYS$SETSFM 
example of use, 6-17 
SYS$SPACE, 4-20 

data structure needed to use, 4-7 to 4-11 
SYS$TRNLNM 
example of use, D-18 
SYS$TRUNCATE, 4-20 
data structure needed to use, 4-7 to 4-11 
SYS$UNWIND, 6-7 
example of use, 6-15 
SYS$UPDATE, 4-20 
data structure needed to use, 4-7 to 4-11 
SYS$WAIT 

data structure needed to use, 4-7 to 4-11 
SYS$WAITFR 
example of use, D-8 
SYS$WAKE 
example of use, D-19 
SYS$WRITE, 4-18, 4-19 
data structure needed to use, 4-7 to 4-11 
example of use, 4-34 
$SYSSRVNAM module 
description of, 3-5 
including, 4-3 
System symbols 

use by system services, 3-5 to 3-6 
using RMS symbols, 4-2 to 4-4 

T 

Task-to-task communications, network, 5-8 
to 5-10 
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Terminal control block 
XABTRM, 4-13 
Terminal I/O 

gathering and displaying data 
examples of SMG routines, D-ll to 
D-13 

Traps and faults 

method of signaling condition handlers, 
6-11 to 6-12 

u 

Underflow, floating 
default processing, 6-13 
user-selected options, 6-13 to 6-14 
Unformatted I/O 
see I/O operations 
Unoptimized programs 
differences and similarities 
to optimized programs, 1-3 to 1-4 
USEREX subroutine 
PDP-11 compatible, B-13 
USEROPEN routines, 4-1 to 4-2 
block mode I/O example, 4-30 to 4-33 
in-depth discussion of, 4-20 to 4-29 
User-written open procedures 
see USEROPEN routines 

V 

%VAL 

argument list built-in function 
for passing arguments to nonFORTRAN 
procs, 3-2 to 3-3 

example of, 3-14, 4-31, 6-18, D-4, D-5 
use with condition handlers, 6-4 
Value propagation optimization, 1-15 to 
1-16 
Variables 

global analysis of use 
for optimization purposes, 1-6 to 1-10 
VOLATILE effects on global analysis, 
1-7, 1-8 

value propagation optimization, 1-15 to 
1-16 

Variable format expressions 
affect on optimizations, 1-10 
VAX Condition Handler Facility, 6-1 to 
6-19 

overview of, 6-1 


VAX FORTRAN 

differences with FORTRAN-66, A-l to 
A-5 

differences with PDP-11 FORTRAN IV, 
B-l to B-5 

differences with PDP-11 FORTRAN-77, 
B-l to B-5 
implementation notes 
see FORTRAN-77, VAX implementation 
of 

PDP-11 utility subroutines supported by 
for compatibility purposes, B-5 to B-13 
VAX RMS 
see RMS 

VAX/VMS system services 
calling by function reference, 3-6 
calling as subroutines, 3-7 
methods of calling and passing arguments, 

3- 5, 3-7 to 3-14 
symbolic names used by, 

for condition values, function codes, 
return status values, 3-5 to 3-6 
see also index entries for SYS$xxxxxx 
see also RMS 
VOLATILE declarations 
effect on optimizations, 1-7 to 1-8 

w 

Write operations 
see I/O operations 

X 

X edit descriptor 

FORTRAN-77 vs. FORTRAN-66, A-4 to 
A-5 
XAB, 4-2 

description of symbol naming conventions, 

4- 3 to 4-5 

general description of use, 4-13 to 4-15 
XABxxx 

nine kinds of XABs 
listing of, 4-13 

z 

ZEXT intrinsic function 
data type conversion, 2-5 
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